Storyblok MCP

MCP server for Storyblok: fetch stories, manage tags, and use AI (Cursor, Claude Desktop) to work with your content. You only need to set 2–3 env variables.

What you need

• Node.js 18+ — nodejs.org (LTS)
• Storyblok Space ID — Space settings or from the app URL: app.storyblok.com/#/me/spaces/<ID>/
• Management API token — Storyblok → Settings → Access tokens → Create (full access or at least Stories + Tags)

Quick start

1. The Universal Way (Best for non-technical users)

Deploy this server to Vercel. Once live, anyone can connect to their own Storyblok space using just the URL and token.

"storyblok": {
  "url": "https://your-server.vercel.app/sse",
  "headers": {
    "Authorization": "Bearer YOUR_TOKEN",
    "x-space-id": "YOUR_SPACE_ID"
  }
}

Advanced Cloud Options (SSE)

You can further customize the connection using headers or URL parameters:

• Specific Space ID: Use the URL .../sse/12345 or set the x-space-id header.
• Custom API Proxy: Set the x-api-base header to point to your own Storyblok MAPI proxy.
• Private Access Key: If the server has an MCP_API_KEY set, provide it via the x-mcp-key header.

Example with all options:

"headers": {
  "Authorization": "Bearer YOUR_TOKEN",
  "x-space-id": "12345",
  "x-api-base": "https://your-proxy.com/v1",
  "x-mcp-key": "your-secret-server-key"
}

2. Local Development

cp env.example .env
npm install
npm run build
node start-with-env.js

Edit .env and set at least:

STORYBLOK_SPACE_ID=12345
STORYBLOK_MANAGEMENT_TOKEN=your-management-token-here

3. Running with Docker

You can also run the server using Docker. This is great for consistent deployments.

docker build -t storyblok-mcp .
docker run -p 3000:3000 \
  -e STORYBLOK_SPACE_ID=your_id \
  -e STORYBLOK_MANAGEMENT_TOKEN=your_token \
  storyblok-mcp

The Docker image defaults to SSE mode on port 3000.

Deploying to Kubernetes

1. Push to Registry:

   docker tag storyblok-mcp your-registry/storyblok-mcp:latest
   docker push your-registry/storyblok-mcp:latest
   

2. Apply Manifests: Use the provided k8s-deployment.yaml as a template. It sets up a Deployment, a Service, and an Ingress for custom domain support (HTTPS).

3. External URL: Once deployed, you can point your domain (e.g., mcp.yourdomain.com) to your Ingress controller's IP.

4. Connect to Cursor or Claude Desktop

Cursor — edit MCP config (e.g. ~/Library/Application Support/Cursor/User/globalStorage/cursor.mcp/mcp.json or Settings → MCP):

{
  "mcpServers": {
    "storyblok": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/storyblok-mcp/start-with-env.js"]
    }
  }
}

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "storyblok": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/storyblok-mcp/start-with-env.js"]
    }
  }
}

Replace the path with your actual storyblok-mcp folder path. Restart Cursor or Claude.

start-with-env.js loads .env from the project folder, so you don’t need to put secrets in the MCP config.

Env variables

Region (EU, US, etc.)

If your Storyblok Space is in the US or another region, set:

STORYBLOK_REGION=us

Options: eu, us, ca, ap, cn. Default: eu.

Custom API URL

Only if you proxy the Storyblok Management API through your own domain:

STORYBLOK_API_BASE=https://your-proxy.com/path

SSE Custom Proxy

In SSE mode, you can also specify the proxy per-connection:

"headers": {
  "x-api-base": "https://your-proxy.com/v1"
}

The proxy must forward to the real Storyblok MAPI. Otherwise leave this unset.

Tools

Full-featured TypeScript implementation for the Storyblok Management API.

Example prompts

• “Fetch my Storyblok stories”
• “List all tags in my space”
• “Suggest a tag for each of my blog posts and add them”
• “Add the tag ‘product-launch’ to story ID …”

Troubleshooting

• “Missing env” — .env must be next to start-with-env.js and contain STORYBLOK_SPACE_ID and STORYBLOK_MANAGEMENT_TOKEN.
• 401 from Storyblok — Token invalid or expired; create a new Management token with Stories + Tags.
• MCP not listed — Use the absolute path to start-with-env.js and restart Cursor/Claude.
• “Cannot find module” — Run npm install and npm run build in your storyblok-mcp folder.

Reference

• Bring your Storyblok data into Claude by coding an MCP server