storyblok-mcp-server

mcp
Guvenlik Denetimi
Uyari
Health Uyari
  • License — License: MIT
  • Description — Repository has a description
  • Active repo — Last push 0 days ago
  • Low visibility — Only 8 GitHub stars
Code Uyari
  • process.env — Environment variable access in src/config.ts
Permissions Gecti
  • Permissions — No dangerous permissions requested

Bu listing icin henuz AI raporu yok.

SUMMARY

A TypeScript MCP server providing 160 tools for the Storyblok Management API

README.md

Storyblok MCP Server

License: MIT
Node.js
MCP
TypeScript

A TypeScript Model Context Protocol server for the Storyblok Management API. It lets AI assistants and agents manage Storyblok content, workflows, and configuration safely and programmatically.

Why this project

Storyblok is powerful, but repetitive content operations and release workflows can be time-consuming. This server bridges MCP-compatible assistants with Storyblok so teams can:

  • Automate content ops (bulk updates, tagging, assets)
  • Orchestrate releases and workflows with less manual effort
  • Keep component libraries and schemas consistent
  • Give AI agents structured, typed access to Storyblok

Highlights

  • 160 tools across 30 modules mapped to Storyblok Management API capabilities
  • Typed schemas with Zod for safer tool calls
  • MCP-first design for MCP-compatible clients
  • Simple config using environment variables

What it does in 15 seconds

Prompt

Find all stories updated in the last 7 days and tag them as "reviewed".

Response (example)

Found 12 stories updated since 2025-12-28.
Applied tag "reviewed" to 12 stories.

Quick Start

# Clone the repository
git clone https://github.com/hypescale/storyblok-mcp-server.git
cd storyblok-mcp-server

# Install dependencies
npm install

# Build
npm run build

Create a .env file from the example and fill in your credentials:

cp .env.example .env

Then start the server:

npm run start

Requirements

  • Node.js >= 20
  • A Storyblok space with Management + Public/Preview tokens

Configuration

The server requires two environment variables (see .env.example):

STORYBLOK_SPACE_ID=your_space_id
STORYBLOK_MANAGEMENT_TOKEN=your_management_token
# Optional: set if your space is not hosted in the EU
STORYBLOK_REGION=eu

What they are used for:

Variable Required Description
STORYBLOK_SPACE_ID yes Your numeric Storyblok space ID
STORYBLOK_MANAGEMENT_TOKEN yes Personal access token for the Management API
STORYBLOK_REGION no Server location of the space: eu (default), us, ca, ap, cn
STORYBLOK_API_BASE_URL no Override the API host entirely (e.g. a proxy); takes precedence over STORYBLOK_REGION
STORYBLOK_DEFAULT_PUBLIC_TOKEN no Not used by any tool; accepted for backwards compatibility

Requests that hit Storyblok's rate limit (HTTP 429; 3–6 req/s depending on plan) are retried automatically with exponential backoff, honoring Retry-After.

Tip: Use the smallest permission set possible for safety.

Usage with MCP Clients

This server is designed to work with any MCP-compatible client. Here are ready-to-copy configs for popular tools.

Claude Desktop

Show config

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "storyblok": {
      "command": "node",
      "args": ["/path/to/storyblok-mcp-server/dist/index.js"],
      "env": {
        "STORYBLOK_SPACE_ID": "your_space_id",
        "STORYBLOK_MANAGEMENT_TOKEN": "your_management_token",
        "STORYBLOK_DEFAULT_PUBLIC_TOKEN": "your_public_token"
      }
    }
  }
}

Codex CLI / IDE

Show config

Codex supports MCP servers via CLI or by editing ~/.codex/config.toml. The CLI and IDE extension share the same config.

Option A: Configure with the Codex CLI

codex mcp add storyblok \
  --env STORYBLOK_SPACE_ID=your_space_id \
  --env STORYBLOK_MANAGEMENT_TOKEN=your_management_token \
  --env STORYBLOK_DEFAULT_PUBLIC_TOKEN=your_public_token \
  -- node /path/to/storyblok-mcp-server/dist/index.js

Option B: Configure with ~/.codex/config.toml

[mcp_servers.storyblok]
command = "node"
args = ["/path/to/storyblok-mcp-server/dist/index.js"]

[mcp_servers.storyblok.env]
STORYBLOK_SPACE_ID = "your_space_id"
STORYBLOK_MANAGEMENT_TOKEN = "your_management_token"
STORYBLOK_DEFAULT_PUBLIC_TOKEN = "your_public_token"

Cursor

Show config

Create a project config at .cursor/mcp.json (or use the global config at ~/.cursor/mcp.json):

{
  "mcpServers": {
    "storyblok": {
      "command": "node",
      "args": ["/path/to/storyblok-mcp-server/dist/index.js"],
      "env": {
        "STORYBLOK_SPACE_ID": "your_space_id",
        "STORYBLOK_MANAGEMENT_TOKEN": "your_management_token",
        "STORYBLOK_DEFAULT_PUBLIC_TOKEN": "your_public_token"
      }
    }
  }
}

Windsurf

Show config

Create ~/.codeium/mcp_config.json:

{
  "mcpServers": {
    "storyblok": {
      "command": "node",
      "args": ["/path/to/storyblok-mcp-server/dist/index.js"],
      "env": {
        "STORYBLOK_SPACE_ID": "your_space_id",
        "STORYBLOK_MANAGEMENT_TOKEN": "your_management_token",
        "STORYBLOK_DEFAULT_PUBLIC_TOKEN": "your_public_token"
      }
    }
  }
}

VS Code

Show config

Create .vscode/mcp.json in your workspace:

{
  "servers": {
    "storyblok": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/storyblok-mcp-server/dist/index.js"],
      "env": {
        "STORYBLOK_SPACE_ID": "your_space_id",
        "STORYBLOK_MANAGEMENT_TOKEN": "your_management_token",
        "STORYBLOK_DEFAULT_PUBLIC_TOKEN": "your_public_token"
      }
    }
  }
}

Continue

Show config

Create a YAML config at .continue/mcpServers/storyblok.yaml:

name: Storyblok MCP
version: 1.0.0
schema: v1
mcpServers:
  - name: storyblok
    command: node
    args:
      - /path/to/storyblok-mcp-server/dist/index.js
    env:
      STORYBLOK_SPACE_ID: your_space_id
      STORYBLOK_MANAGEMENT_TOKEN: your_management_token
      STORYBLOK_DEFAULT_PUBLIC_TOKEN: your_public_token

Cline

Show config

Open Cline settings and use "Configure MCP Servers" to open cline_mcp_settings.json, then add:

{
  "mcpServers": {
    "storyblok": {
      "command": "node",
      "args": ["/path/to/storyblok-mcp-server/dist/index.js"],
      "env": {
        "STORYBLOK_SPACE_ID": "your_space_id",
        "STORYBLOK_MANAGEMENT_TOKEN": "your_management_token",
        "STORYBLOK_DEFAULT_PUBLIC_TOKEN": "your_public_token"
      }
    }
  }
}

Available Tools

The tool surface mirrors Storyblok's Management API. Total tool count and modules are defined in src/tools/index.ts.

Module Tools Description
Stories 18 CRUD, bulk operations, publishing, versioning
Components 9 Schema management, versioning, usage tracking
Assets 9 Upload, organize, bulk operations
Workflows 6 Workflow management and stages
Releases 5 Release scheduling and deployment
Datasources 5 Key-value data management
Tags 5 Content tagging and organization
Webhooks 5 Event notifications
Collaborators 4 Team management
Space Roles 5 Permissions and access control
... ... And 20+ more modules

Example Prompts

Use these prompts in your MCP client to see quick wins:

  • "List all stories updated in the last 7 days and tag them as 'reviewed'."
  • "Create a release for next Friday and add the homepage and pricing stories."
  • "Find unused components and tell me which stories still reference them."
  • "Upload these assets and organize them into a new 'Campaign' folder."

Development

# Run in development mode with hot reload
npm run dev

# Type check
npm run typecheck

# Run unit tests
npm test

# Build for production
npm run build

Project Structure

  • src/index.ts - MCP server entry point
  • src/tools/* - Tool modules mapped to Storyblok API areas
  • src/types/* - Shared API and Storyblok types
  • src/tools/registry.ts - Module registration, tool counts and MCP tool annotations
  • src/utils/* - HTTP helpers (retry, region, errors) and response formatting
  • src/config.ts - Environment configuration and validation

Troubleshooting

  • ConfigError: STORYBLOK_* is missing - ensure .env is present and filled out.
  • Run the ping tool first: it verifies token, region and space ID in one call.
  • 401 Unauthorized - verify STORYBLOK_MANAGEMENT_TOKEN.
  • 404 Not Found - double-check STORYBLOK_SPACE_ID, and that STORYBLOK_REGION matches where the space is hosted.

Tech Stack

  • TypeScript with strict type checking
  • @modelcontextprotocol/sdk for MCP implementation
  • Zod for runtime schema validation
  • Native fetch API for HTTP requests

Release and Versioning

When you're ready to cut a release:

  1. Update package.json version (semantic versioning recommended).
  2. Update README.md if behavior or setup changed.
  3. Tag the release and publish a GitHub Release with notes.

This keeps the project easy to consume for open source users and downstream tools.

Security Notes

  • Never commit .env files or tokens to git.
  • Prefer tokens scoped to a dedicated Storyblok space for automation.
  • Rotate tokens if you suspect exposure.

Contributing

Issues and PRs are welcome. If you're planning a large change, open an issue first so we can align on scope and direction.

License

MIT


Built by hypescale | Maintained by Martin Kogut

Yorumlar (0)

Sonuc bulunamadi