Integration · AI

BetterCMS MCP server

The BetterCMS MCP server lets an AI assistant author your content schema, entries, forms and components through the Management API. It authenticates with a short lived, per project content:manage key minted by the OAuth 2.0 device flow, so no long lived key is ever pasted into a client. Every tool it exposes is additive. There is no tool that deletes anything.

Package
@bettercms-ai/mcp
Auth
Device flow, short lived key
Destructive tools
None

Set it up

Four steps. Step one only applies until the package moves to the public npm registry.

  1. 01 Authorize the package registry
  2. 02 Add the server to your client
  3. 03 Approve the device
  4. 04 Ask for something and review it

The credential cache defaults to ~/.bettercms/mcp-credentials.json at mode 0600, and BETTERCMS_MCP_CREDENTIALS moves it. BETTERCMS_MCP_CLIENT_NAME sets the label shown on the approval screen, which is worth setting when several machines share one account.

  1. 01

    Authorize the package registry

    The package is published to GitHub Packages today, which requires authentication even for a public scoped package. Without this, the npx command in step two cannot resolve.

    Publishing to npmjs.org is on the roadmap, and this step disappears when it lands.

    ~/.npmrc
    @bettercms-ai:registry=https://npm.pkg.github.com/
    //npm.pkg.github.com/:_authToken=<GitHub token with read:packages>
  2. 02

    Add the server to your client

    Claude Code, Claude Desktop and any other MCP client take the same shape. No key goes in this file.

    MCP client config
    {
      "mcpServers": {
        "bettercms": {
          "command": "npx",
          "args": ["-y", "@bettercms-ai/mcp"],
          "env": { "BETTERCMS_API_URL": "https://api.bettercms.ai" }
        }
      }
    }
  3. 03

    Approve the device

    On the first tool call the server prints an authorization prompt to its logs with a short code. Open the activation page, enter the code, and pick the workspace and project the assistant is allowed to touch.

    The minted token is cached locally and refreshes itself. Revoke it and the device flow runs again.

    server log
    BetterCMS authorization required
    Visit: https://bettercms.ai/activate
    Enter code: WDJB-MJHT
  4. 04

    Ask for something and review it

    The assistant can create a model, append a field, create an entry, author a form, and author a reusable component, then list forms and components so it can wire them into site code.

    Everything it does lands in the dashboard where a person reads it. The server is a way in, not a way to skip review.

What the tools do

  • Author a model

    create_model makes a content model with optional initial fields. add_field appends a field to a model it reads first, so it never removes one.

  • Author an entry

    create_entry creates a content entry and applies its data and status through a follow up update.

  • Author a form

    create_form and update_form author a form with its fields and settings, ready to render with the form component in your framework.

  • Author a component

    create_component and update_component author a reusable component as a block tree with props, which the block renderer then draws on any page that uses it.

  • Discover what exists

    list_forms, get_form, list_components and get_component let the assistant find what is already there before it wires anything into site code.

  • Nothing that deletes

    There is no delete tool of any kind. Removing a model, a field or an entry is a dashboard action, deliberately, so an assistant cannot destroy content it misunderstood.

What it does not do

  • It cannot delete anything

    This is the headline constraint and it is a feature. Deleting models, fields or entries is dashboard only by design, so the worst an assistant can do is create something you did not want.

  • It resolves from GitHub Packages today

    Until the package is published to npmjs.org, npx needs an ~/.npmrc entry with a GitHub token carrying read:packages. Any guide that skips that step fails on the first command.

  • It is scoped to one project at a time

    The device flow mints a key for the workspace and project you pick on the approval screen. An assistant does not get the account, it gets that project.

  • It is not a review process

    The MCP server is a way for an assistant to write into the CMS. Reading what it wrote and deciding whether to publish it is still a person, in the dashboard.

Questions people ask

  • It is a Model Context Protocol server that lets an AI assistant author content schema, entries, forms and components in a BetterCMS project through the Management API. It runs locally through npx, authenticates with a short lived per project key minted by the OAuth 2.0 device flow, and exposes only additive tools.

  • No. There is no destructive tool in the server. Deleting a model, a field or an entry is a dashboard action by design. add_field is the clearest example of the rule: it reads the model, appends, and writes back, so it cannot drop a field it did not understand.

  • No, and you should not. The client config carries no secret. On the first tool call the server prints a short code, you approve it on the activation page and pick the workspace and project, and the minted token is cached locally at mode 0600 and refreshed automatically.

  • Because the package is published to GitHub Packages today, and GitHub Packages requires authentication even for public scoped packages. Add an ~/.npmrc entry mapping the @bettercms-ai scope to npm.pkg.github.com with a token that has read:packages. Publishing to the public npm registry is planned, and this step goes away when it happens.

Your next website starts here

See BetterCMS running on your pages, not on a sample site.