@clearcms/mcp

A Model Context Protocol server that exposes a clear bucket as native tools to LLM agents — Claude Desktop, Claude Code, and any other MCP-aware client.

Why this exists: clear's bucket-as-protocol design means an agent can read and write content the same way the admin UI does. This package packages that surface as a single npx command.

Install

The package is published as @clearcms/mcp. There is nothing to install globally — npx (or your client's command field) pulls it on demand.

Wire it into Claude Code

Add to your project's .mcp.json:

{
  "mcpServers": {
    "clearcms": {
      "command": "npx",
      "args": [
        "-y",
        "@clearcms/mcp",
        "--base-url=http://localhost:3001",
        "--token=clr_..."
      ]
    }
  }
}

--token is only required if the agent needs to read drafts (read:drafts scope) or write items. For published-content reads it can be omitted.

Wire it into Claude Desktop

Edit claude_desktop_config.json (location varies by OS — Claude Desktop has the path under Settings → Developer → Edit Config):

{
  "mcpServers": {
    "clearcms": {
      "command": "npx",
      "args": ["-y", "@clearcms/mcp", "--base-url=http://localhost:3001"]
    }
  }
}

Restart Claude Desktop. The clear tools appear in the "tools" hammer-icon panel.

Connection modes

@clearcms/mcp supports two ways to talk to a clear instance.

| Mode | Flag | Capabilities | | --- | --- | --- | | REST (default) | --base-url=<admin-url> --token=<api-token> | Read + search + create + update + delete | | Filesystem | --bucket-root=<path> | Read-only |

In REST mode the server forwards reads through the admin's /api/v1/* and writes through its Astro Actions endpoints (/_actions/items.*). Writes therefore round-trip through the admin's items service, so the index, plugin hooks, and webhooks all fire correctly.

In FS mode the server reads bucket files directly via @clearcms/sdk's fs adapter. Writes are intentionally not supported — they need the admin's items service for the index update + plugin invocation.

Environment-variable equivalents: CLEARCMS_BASE_URL, CLEARCMS_TOKEN, CLEARCMS_BUCKET_ROOT.

Tools

| Tool | Description | | --- | --- | | cms_describe | Returns /api/v1/llms.txt — site identity, every collection + field, every endpoint, content index. Read first. | | cms_list | List items in a collection (paginated). | | cms_get | Fetch one item by collection + slug. | | cms_create | Create an item; defaults to draft, can publish atomically. | | cms_update | Patch an item's data; can publish atomically. | | cms_delete | Soft-delete (move to trash, recoverable for 30 days). | | cms_search | Full-text search over title + body across one or many collections. | | cms_get_page | Read a URL-bound page document. | | cms_list_pages | List every published page. | | cms_schema | Return a collection's field schema. Use before cms_create / cms_update. |

Smoke-test it

pnpm -r --filter @clearcms/mcp build
node public/packages/mcp/scripts/smoke.mjs

The smoke test spawns the server, performs the MCP handshake, and asserts that tools/list returns the 10 tools above. No clear admin is required — the SDK is constructed lazily.

Caveats

• Writes are session-cookie-free. Astro Actions on /_actions/* are open to the network in v0; they are gated by the same admin process running locally. For non-localhost deploys, gate the admin upstream (reverse proxy + IP allowlist, or wait for the Bearer-authed write surface that's on the protocol roadmap).
• cms_search, cms_describe, cms_schema require REST mode. FTS lives in the admin DB and llms.txt is server-rendered — no fs equivalent today.
• Locale on pages is forward-compat only. Pages are single-locale in v0; the locale arg on cms_get_page / cms_list_pages is accepted but currently ignored.

License

MIT — see LICENSE.