@betttercms/mcp

BetterCMS Model Context Protocol server. Lets an AI assistant author your content schema and entries through the BetterCMS Management API, authenticated with a short-lived, per-project content:manage key minted via the OAuth 2.0 Device Authorization Grant (RFC 8628) — no pasted long-lived key.

Tools

| Tool | Description | |------|-------------| | create_model | Create a content model (schema) with optional initial fields. | | add_field | Append a field to an existing model (read-modify-write; never removes fields). | | create_entry | Create a content entry; applies data/status via a follow-up update. | | create_form / update_form | Author a form (fields + settings) to embed with <BcmsForm>. | | create_component / update_component | Author a reusable component (blockJson tree + props) to render with <BcmsBlocks>. | | list_forms / get_form / list_components / get_component | Discover forms & components to wire into site code. |

See SKILL.md for how an AI agent should author pages, forms, and components.

All operations are additive — there are no destructive tools. Deleting models, fields, or entries is dashboard-only by design.

Usage

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

{
  "mcpServers": {
    "bettercms": {
      "command": "npx",
      "args": ["-y", "@betttercms/mcp"],
      "env": { "BETTERCMS_API_URL": "https://api.bettercms.ai" }
    }
  }
}

Registry auth (current)

This package is published to GitHub Packages, which requires authentication even for public scoped packages. For npx @betttercms/mcp to resolve, the host machine needs an ~/.npmrc with:

@bettercms:registry=https://npm.pkg.github.com/
//npm.pkg.github.com/:_authToken=<a GitHub PAT with read:packages>

TODO (future): publish @betttercms/mcp (and types/sdk) to the public npmjs.org registry so npx @betttercms/mcp works with zero .npmrc setup for any host/user. Until then the GitHub Packages auth above is required.

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://demo.bettercms.ai/activate
│ Enter code: WDJB-MJHT
│ Or open: https://demo.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. |

Develop

bun install
bun run --filter @betttercms/mcp typecheck
bun run --filter @betttercms/mcp test
bun run --filter @betttercms/mcp build