@bettercms-ai/mcp

BetterCMS Model Context Protocol server, as a local stdio process. It signs in with the OAuth 2.0 Device Authorization Grant (RFC 8628): no pasted long-lived key.

Most people should use the hosted server instead: add https://mcp.bettercms.ai/mcp to your client, or run npx @bettercms-ai/install --mcp. This package exposes the same tools for clients that only speak stdio. Setup per client and the full tool reference: https://bettercms.ai/docs/ai/connect-mcp and https://bettercms.ai/docs/ai/mcp-tools

Tools

The same tool set as the hosted server: pages and sections, content models and fields, entries, components, media, forms, SEO, publishing and deploys, and more. Writes stay drafts unless you allowed publishing when you approved the client. Agents learn the order of work from the bettercms skill (npx @bettercms-ai/install).

Usage

Add to your MCP client config (e.g. Claude Desktop / Claude Code):

{
  "mcpServers": {
    "bettercms": {
      "command": "npx",
      "args": ["-y", "@bettercms-ai/mcp"]
    }
  }
}

On the first tool call the server prints an authorization prompt to stderr (visible in your MCP client's logs):

┌─ BetterCMS authorization required ─────────────────────────
│ Visit: https://bettercms.ai/activate
│ Enter code: WDJB-MJHT
│ Or open: https://bettercms.ai/activate?code=WDJB-MJHT
└────────────────────────────────────────────────────────────

Approve it in the dashboard (pick a workspace/project) and the server caches the minted token. It auto-refreshes on expiry; if the refresh token is revoked it re-runs the device flow.

Environment

| Var | Default | Purpose | |-----|---------|---------| | BETTERCMS_API_URL | https://api.bettercms.ai | API origin (device-auth + Management API). | | BETTERCMS_MCP_CREDENTIALS | ~/.bettercms/mcp-credentials.json | Token cache path (0600). | | BETTERCMS_MCP_CLIENT_NAME | BetterCMS MCP | Label shown on the approval screen. | | BETTERCMS_MCP_TOOLS | (unset) | Toolsets to register, a comma list: core (core tools only), abm (adds the ABM campaign lane), all. Unset registers every tool except the ABM lane. The hosted server takes the same list as ?tools=. |

Develop

bun install
bun run --filter @bettercms-ai/mcp typecheck
bun run --filter @bettercms-ai/mcp test
bun run --filter @bettercms-ai/mcp build