cascade-cms

cascade-cms-mcp-server

An MCP (Model Context Protocol) server that exposes Cascade CMS operations to LLMs and agents. It wraps cascade-cms-api with Zod validation, JSON responses, structuredContent, and actionable errors.

Built in TypeScript on Bun. It provides Cascade asset tools, draft workflows, file-data helpers, browser-backed tools, guardrails, and local cache inspection.

Start with Setup for required values and client config. Use What It Can Do to judge fit. Agent Reference covers tool-call mechanics.

Setup

Requirements

• Node 20+.
• Bun 1.0+ for the preferred bunx setup.
• A Cascade CMS instance with REST API access and an API key.
• An MCP client that can launch stdio servers, such as Claude, Codex, Cline, MCP Inspector, or another compliant client.

Quick Start

Most MCP clients need command, args, CASCADE_API_KEY, and CASCADE_URL. Browser-backed tools also need CASCADE_BROWSER_USERNAME, CASCADE_BROWSER_PASSWORD, and CASCADE_BROWSER_SITE_ID. Use bunx when available; use npx otherwise.

The credentials below are placeholders. Use your MCP client's secret/env handling, local environment, or dotseal-encrypted values for real credentials.

For Cascade API access, consider using a dedicated service/API user when your organization can provide one. Give that user only the permissions needed for the MCP workflows instead of using a personal account.

MCP Client Config

Use one of these shapes for JSON-based MCP configs.

{
  "mcpServers": {
    "cascade-cms": {
      "command": "bunx",
      "args": ["cascade-cms-mcp-server"],
      "env": {
        "CASCADE_API_KEY": "your_api_key_here",
        "CASCADE_URL": "https://yourorg.cascadecms.com/api/v1/",
        "CASCADE_BROWSER_USERNAME": "browser_username",
        "CASCADE_BROWSER_PASSWORD": "browser_password",
        "CASCADE_BROWSER_SITE_ID": "production_site_id",
        "CASCADE_BROWSER_URL": "https://yourorg.cascadecms.com/"
      }
    }
  }
}

Node/npm fallback:

{
  "mcpServers": {
    "cascade-cms": {
      "command": "npx",
      "args": ["-y", "cascade-cms-mcp-server"],
      "env": {
        "CASCADE_API_KEY": "your_api_key_here",
        "CASCADE_URL": "https://yourorg.cascadecms.com/api/v1/",
        "CASCADE_BROWSER_USERNAME": "browser_username",
        "CASCADE_BROWSER_PASSWORD": "browser_password",
        "CASCADE_BROWSER_SITE_ID": "production_site_id",
        "CASCADE_BROWSER_URL": "https://yourorg.cascadecms.com/"
      }
    }
  }
}

Omit CASCADE_BROWSER_URL when the browser login host matches the origin derived from CASCADE_URL.

For UI-based clients, enter the same values:

Field	Bun value	Node/npm value
Command	bunx	npx
Arguments	cascade-cms-mcp-server	-y, cascade-cms-mcp-server
Environment	CASCADE_API_KEY, CASCADE_URL, browser env values when using browser-backed tools, optional CASCADE_TIMEOUT_MS	Same

Restart the client after config changes. Call cascade_server_version to confirm the server is running.

Client-Specific Examples

Client-specific setup screens and config file locations vary. Use the same command, args, and env values above.

Codex uses ~/.codex/config.toml:

[mcp_servers.cascade-cms]
command = "bunx"
args = ["cascade-cms-mcp-server"]

[mcp_servers.cascade-cms.env]
CASCADE_API_KEY = "your_api_key_here"
CASCADE_URL = "https://yourorg.cascadecms.com/api/v1/"
CASCADE_BROWSER_USERNAME = "browser_username"
CASCADE_BROWSER_PASSWORD = "browser_password"
CASCADE_BROWSER_SITE_ID = "production_site_id"
CASCADE_BROWSER_URL = "https://yourorg.cascadecms.com/"

Claude Desktop uses claude_desktop_config.json:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Claude Code can use its normal MCP config flow. This repo also includes a Claude Code plugin manifest in .claude-plugin/plugin.json; if you install the plugin, set credentials in the shell environment that launches Claude Code.

Native Windows configs that use npx may need command: "cmd" with args ["/c", "npx", "-y", "cascade-cms-mcp-server"].

Encrypted Environment Values

All environment values below may use dotseal ciphertexts in enc:<iv>:<authTag>:<ciphertext> format. Plaintext values still work.

Generate ciphertext with dotseal:

bunx dotseal encrypt "your_api_key_here"

Example: