# Storyblok MCP

MCP server for [Storyblok](https://www.storyblok.com): 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](https://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. 

```json
"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:**
```json
"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

```bash
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.

```bash
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**:
   ```bash
   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](./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):

```json
{
  "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):

```json
{
  "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

| Variable | Required | Description |
|----------|----------|-------------|
| `STORYBLOK_SPACE_ID` | ✅ | Your Storyblok space ID |
| `STORYBLOK_MANAGEMENT_TOKEN` | ✅ | Management API token |
| `STORYBLOK_REGION` | ❌ | `eu` (default), `us`, `ca`, `ap`, `cn` — use if your Space is not in EU |
| `STORYBLOK_API_BASE` | ❌ | Override API base (if proxying) |

### 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:
```json
"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.

| Category | Tools |
|----------|-------|
| **Stories** | `fetch_stories`, `get_story`, `create_story`, `update_story`, `delete_story`, `publish_story`, `unpublish_story`, `get_story_versions` |
| **Tags** | `fetch_tags`, `create_tag`, `create_tag_and_add_to_story`, `add_existing_tag_to_story`, `update_tag`, `delete_tag` |
| **Components** | `fetch_components`, `get_component`, `create_component`, `update_component`, `delete_component` |
| **Assets** | `fetch_assets`, `get_asset`, `update_asset`, `delete_asset` |
| **Releases** | `fetch_releases`, `get_release`, `create_release`, `update_release`, `delete_release` |
| **Workflows** | `fetch_workflows`, `get_workflow`, `create_workflow`, `update_workflow`, `delete_workflow`, `fetch_workflow_stages` |
| **Webhooks** | `fetch_webhooks`, `get_webhook`, `create_webhook`, `update_webhook`, `delete_webhook` |
| **Datasources** | `fetch_datasources`, `get_datasource`, `create_datasource`, `update_datasource`, `delete_datasource`, `fetch_datasource_entries`, `create_datasource_entry`, `update_datasource_entry`, `delete_datasource_entry` |
| **Space** | `get_space`, `update_space` |
| **Meta** | `list_tools` — list all tools by category |
| **Ping** | `ping` — health check (optional `check_api=1` to test 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](https://www.storyblok.com/tp/bring-your-storyblok-data-into-claude-by-coding-an-mcp-server)