@timelesscms-com/mcp-server

Model Context Protocol server for the TimelessCMS public API. Lets Claude Code (or any MCP-compatible client) manage a TimelessCMS site through the same tool surface a human agency would use: read and write pages, partials, collections, media, redirects, versions; trigger deploys; mint preview links.

The server is a thin transport adapter — every tool wraps one HTTP endpoint of the TimelessCMS REST API. Auth happens at the API layer with a site-scoped key; the MCP just carries the bearer through.

Quick start

1. Create an API key in your TimelessCMS portal at /app/sites/{siteId}/settings/api-keys. The key is shown once at creation — copy it somewhere safe.

2. Add the server to Claude Code. Drop this into ~/.claude.json (or your local .claude/config.json):

   {
     "mcpServers": {
       "timelesscms": {
         "command": "npx",
         "args": ["-y", "@timelesscms-com/mcp-server"],
         "env": {
           "TCMS_API_URL": "https://app.timelesscms.com",
           "TCMS_API_KEY": "tcms_live_REPLACE_WITH_YOUR_KEY"
         }
       }
     }
   }

   For a self-hosted portal, point TCMS_API_URL at it (e.g. https://cms.example.com).

3. Tell the agent what kind of work you want. A good first message:

   "Connect to TimelessCMS and tell me what you find — site name, number of pages, what global blocks exist, what collections are defined. Then I'll give you a task."

   Claude will call get_site, list_pages, list_partials, list_collections in sequence and report back.

Environment variables

| Var | Required | Description | |-----------------|----------|-------------| | TCMS_API_URL | yes | Base URL of your TimelessCMS portal. | | TCMS_API_KEY | yes | A tcms_live_… bearer token from the API keys page. | | TCMS_SITE_ID | no | Pin the server to a specific site. Defaults to autodetect (calls GET /v1/sites — per-site keys return exactly one). |

What the agent should read first

The package ships AGENTS.md, a self-contained briefing that explains TimelessCMS conventions, common operations, and the safety boundaries an agent needs to respect. Point Claude at it (or include it in your project's CLAUDE.md / AGENTS.md) so it knows when to use which tool.

Tool surface

Around 50 tools across these families. See AGENTS.md for the full reference + concrete operation recipes.

• Discovery — get_site, update_site (name/slug/domain), list_versions, read_site_settings, update_site_settings.
• Pages — list, read, batch-read, create, update (PATCH), replace (PUT), batch-update, delete, clone, get-blocks, get-preview.
• Global blocks (partials) — list (summary mode by default), read, create free block, update, replace, delete, find-pages-using-block.
• Block types — list, read, find-pages-using-block-type. Surface for the future block editor.
• Collections + items — create/update/delete the collection schema itself (incl. route_template for per-item URLs); list/read/batch- read/create/update/delete items.
• Media — list, read, signed upload URLs, upload_media_from_url, upload_media_inline, patch metadata, delete, generate_image_variants (build-time srcset pipeline), suggest_alt_text_context (returns a tuned prompt for your own vision model).
• Redirects — list, create, delete. Plus automatic 301 on slug change.
• Forms — list, read, create, update, delete, list submissions.
• Settings — read + patch (scripts and custom CSS not exposed).
• Search — search_pages with substring or regex.
• Bulk — bulk_replace_text with dry-run.
• Branches — create, read, delete, merge. Branch deploys get their own URL at {branch}.{project}.pages.dev.
• Deploy — trigger, list, get status.
• Preview — get_preview_link (signed URL for browser navigation; supports page_id, slug, or collection_name + item_id).

Direct REST API access

If you don't want the MCP wrapper, the same surface is reachable directly with curl:

curl -H "Authorization: Bearer tcms_live_..." \
  https://app.timelesscms.com/api/v1/sites/<siteId>/pages

The MCP server is purely an ergonomics layer on top of that.

Security model

• API keys are site-scoped. A key cannot read or write another site in the same organization — server-side authoritative.
• All write calls (POST, PUT, PATCH, DELETE) are audit-logged with the key prefix, IP, method, path, and status. Reads are not logged (cost vs. value).
• Rate limits: 600 reads/min, 60 writes/min per key. 429 responses carry Retry-After headers.
• HTML sanitization happens at save time on the server — <script>, event handlers, and javascript: URLs are stripped. The customer's scripts_* and custom_css settings are read-stripped and write-dropped by the API.
• Keys can be revoked at any time from the portal. Revocation takes effect on the next request (no in-flight requests get cancelled, but the next one returns 401).

More

• Full end-to-end production setup recipe with troubleshooting: docs/claude-code-mcp-setup.md
• Agent operations briefing: AGENTS.md
• Boilerplate skills (migration, content, images, directory, redesign): skills/

License

MIT — see LICENSE.