Docs / Tools

Crumbless MCP

Crumbless exposes a Model Context Protocol server so coding agents (Cursor, Claude, and others) can manage brands, posts, plans, Brand Kit, SEO/GEO, and blog — with the same OAuth login as the CLI.

stdio → cli/mcp/stdio.ts → /api/v1/*

Quick start

Pick a transport: local stdio is simplest on your machine; remote HTTP is for cloud hosts.

These local examples require a configured app checkout, app and CLI dependencies, and Bun. Start the app with npm run dev from the repository root and wait for its ready message. Use its actual origin: http://localhost:5173 below is only an example, not an assumed running service. Run CLI commands from cli/. Set PUBLIC_APP_URL before login and every command, and set the same value in each separately launched MCP process's env configuration. Without this pin, local detection can fall back to production. The MCP listener on port 8787 is not the app origin. No hosted installer or published package is assumed.

Option A — Local stdio

Best for Cursor and other local agents.

1. Use a local checkout of this repository with Bun and CLI dependencies available. The stdio entrypoint is cli/mcp/stdio.ts.
2. Authenticate once:

   export PUBLIC_APP_URL="http://localhost:5173"
   bun run cli.ts login

3. Add to Cursor MCP config (absolute path required when using Bun):

   {
     "mcpServers": {
       "crumbless": {
         "command": "bun",
         "args": ["run", "/absolute/path/to/crumbless-app/cli/mcp/stdio.ts"],
         "env": { "PUBLIC_APP_URL": "http://localhost:5173" }
       }
     }
   }

   If the binary is on PATH after install:

   {
     "mcpServers": {
       "crumbless": {
         "command": "crumbless-mcp",
         "env": { "PUBLIC_APP_URL": "http://localhost:5173" }
       }
     }
   }

4. Restart Cursor / reload MCP. Call list_brands, then work with a brand slug.

Session file (shared with the CLI): ~/.config/crumbless/session.json.

Option B — Remote HTTP

HTTP transport exists in the source, but a hosted Crumbless MCP service is not established here. Use local stdio, or an HTTP endpoint your operator has deployed and provided. Do not guess a service URL.

For an operator-provided HTTP endpoint, use its browser OAuth flow. REST API keys are not a substitute for an MCP OAuth session.

Option C — Local HTTP

export PUBLIC_APP_URL="http://localhost:5173"
bun run mcp:http

http://localhost:8787/mcp · http://localhost:8787/health

Auth: Bearer or the local session file.

Auth rules

Protected resource metadata: GET /.well-known/oauth-protected-resource.

What to call first

1. list_brands — discover brand slugs
2. get_dashboard — brand overview
3. list_posts with status pending_user — approval queue
4. Prefer specific tools (approve_posts, edit_post, …) over chat for precise actions

Post and article ids accept short unambiguous prefixes from list results (same rule as the CLI).

Tool areas

Troubleshooting

Next

• Agent skill — install the Crumbless skill so agents know when and how to call MCP or the CLI
• CLI — terminal commands when MCP is not available
• API reference — REST endpoints the MCP and CLI call
• anomalia — historical upstream project, not a Crumbless installation source