@r3lab/cms-mcp

A Model Context Protocol (MCP) server for the R3Lab CMS. It lets AI agents (Claude Desktop, Claude Code, Cursor, etc.) manage a website's content types, content, media/images, and leads through a CMS API key.

Every request is scoped to a website. With a website-scoped API key that scope is fixed to the website the key was created for. With a master API key the scope is chosen per request via an optional websiteId tool argument. See Master keys below.

Requirements

• Node.js >= 18
• A CMS API key (Settings → API Keys in the CMS)
• The CMS base URL (e.g. https://cms.r3lab.dev)

Configuration

The server reads two environment variables:

| Variable | Required | Description | | ------------- | -------- | --------------------------------------------- | | CMS_API_KEY | yes | API key generated in the CMS (cms_…). | | CMS_URL | yes | CMS base URL, no trailing slash. |

Usage

Claude Desktop / Cursor

Add to your MCP config (claude_desktop_config.json or equivalent):

{
  "mcpServers": {
    "r3-cms": {
      "command": "npx",
      "args": ["-y", "@r3lab/cms-mcp"],
      "env": {
        "CMS_API_KEY": "cms_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "CMS_URL": "https://cms.r3lab.dev"
      }
    }
  }
}

Claude Code (CLI)

claude mcp add r3-cms \
  --env CMS_API_KEY=cms_xxx \
  --env CMS_URL=https://cms.r3lab.dev \
  -- npx -y @r3lab/cms-mcp

Local development

yarn workspace @r3lab/cms-mcp build
CMS_API_KEY=cms_xxx CMS_URL=http://localhost:3000 node packages/cms-mcp/dist/index.js

Master keys

A CMS API key is either website-scoped (bound to one website) or master (manages ALL websites). For a master key, every tool below accepts an optional websiteId argument that is sent as the x-website-id request header to select which website the call applies to. Website-scoped keys ignore (or must match) that header since their scope is already fixed by the key itself.

Use the cms_*_website tools (see Websites below) to manage the websites a master key can target.

Tools

Websites

| Tool | Description | | ---------------------- | ----------------------------------------------------- | | cms_list_websites | List websites (see Master keys). | | cms_create_website | Create a website (master keys only). | | cms_update_website | Update a website. | | cms_delete_website | Delete a website (master keys only). |

Content types

| Tool | Description | | -------------------------- | -------------------------------------------- | | cms_list_content_types | List all content types (schemas). | | cms_get_content_type | Get one content type by name. | | cms_create_content_type | Create a content type with field definitions.| | cms_update_content_type | Update a content type (replaces fields). | | cms_delete_content_type | Delete a content type (if unused). |

Content

| Tool | Description | | ---------------------------- | ------------------------------------------ | | cms_list_content | List entries of a type (filter/search/sort/page). | | cms_get_content | Get an entry by id. | | cms_get_content_by_slug | Get an entry by type + slug. | | cms_create_content | Create an entry (validated against schema).| | cms_update_content | Update an entry. | | cms_delete_content | Delete an entry. | | cms_publish_content | Publish an entry. | | cms_unpublish_content | Unpublish an entry (back to draft). | | cms_list_content_versions | List an entry's version history. |

Media

| Tool | Description | | ------------------- | ----------------------------------------------------- | | cms_list_media | List media assets (filter by type / filename). | | cms_get_media | Get one media asset by id. | | cms_upload_image | Upload from url, local filePath, or base64. Images are auto-compressed to webp. | | cms_update_media | Update alt text / filename. | | cms_delete_media | Delete a media asset (object + record). |

Leads

| Tool | Description | | ------------------ | --------------------------------------------- | | cms_list_leads | List leads (filter by status, search). | | cms_get_lead | Get a lead by id. | | cms_create_lead | Create a lead. | | cms_update_lead | Update a lead (fields and/or pipeline status).| | cms_delete_lead | Delete a lead. |

How it works

The server is a thin, stateless client over the CMS's API-key REST endpoints (/api/websites, /api/content-types, /api/content, /api/media, /api/leads). It sends the key in the x-api-key header and, when a tool is called with websiteId, the target website in the x-website-id header. The CMS resolves the effective website scope from the key (and header, for master keys) and records API usage. Logs go to stderr so the stdio JSON-RPC channel stays clean.