# Storyblok MCP Server 🚀 The Storyblok MCP ([Model Context Protocol](https://modelcontextprotocol.io/introduction)) server enables your AI assistants to directly access and manage your Storyblok spaces, stories, components, assets, workflows, and more.

## What Does It Do? With the Storyblok MCP Server, your AI assistant can: - **Create** - Create new stories, components, assets, datasources, tags, releases, workflows, and more. - **Read** - Read all your stories, components, assets, datasources, tags, releases, workflows, and more. - **Update** - Update existing/new stories, components, assets, datasources, tags, releases, workflows, and more. - **Delete** - Delete specific/all your stories, components, assets, datasources, tags, releases, workflows, and more. --- ## 🚀 Features - **Full Storyblok Management**: CRUD for stories, components, assets, datasources, tags, releases, workflows, and more.(Covered everything) - **Modular Tooling**: Each Storyblok resource is managed by its own tool module for easy extension and maintenance. - **Meta Tool**: Discover all available tools and their descriptions at runtime. - **Async & Fast**: Built on `httpx` and `FastMCP` for high performance. - **Environment-based Config**: Securely manage tokens and space IDs via `.env`. - **Bulk Operations**: Efficiently update, delete, or publish multiple resources at once. --- ## 📦 Project Structure ``` ├── config.py # Loads and validates environment config ├── server.py # Main entrypoint, registers all tools ├── tools/ # All modular tool implementations │ ├── components.py # Component CRUD and usage │ ├── stories.py # Story CRUD, bulk ops, validation │ ├── ... # (assets, tags, releases, workflows, etc.) │ └── meta.py # Meta tool for tool discovery ├── utils/ │ └── api.py # API helpers, error handling, URL builders ├── .env # Your Storyblok tokens and space ID ├── pyproject.toml # Python dependencies └── README.md # This file ``` --- ## 🚀 API Coverage | Resource | Description | |----------------------------|--------------------------------------------------| | Access Tokens | Manage access tokens for Storyblok API | | Activities | Manage or retrieve activity logs | | Approvals | Manage approval workflows | | Assets | Manage assets (upload, update, delete, list) | | Assets Folder | Manage asset folders | | Branch Deployments | Manage branch deployments | | Collaborators | Manage collaborators in a space | | Components | Manage Storyblok components (CRUD, schema, etc.) | | Components Folder | Manage folders for components | | Datasource Entries | Manage entries in data sources | | Data Sources | Manage data sources (CRUD, entries) | | Discussions | Manage discussions and comments | | Extensions | Manage Storyblok extensions | | Field Plugins | Manage custom field plugins | | Internal Tags | Manage internal tags for assets/stories | | Meta | Meta tool: discover all available tools | | Ping | Health check and server status | | Pipelines | Manage pipelines for content delivery | | Presets | Manage field presets for components | | Releases | Manage releases (create, update, publish) | | Scheduling Stories | Schedule stories for publishing | | Space | Manage Storyblok space settings and info | | Space Roles | Manage roles and permissions in a space | | Stories | Manage stories (CRUD, bulk ops, validation) | | Tags | Manage tags (CRUD, bulk association) | | Tasks | Manage tasks (CRUD, webhooks, automation) | | Webhooks | Manage webhooks (CRUD, trigger) | | Workflows | Manage workflows and workflow stages | | Workflow Stage | Manage individual workflow stages | | Workflow Stage Changes | Track and manage workflow stage changes | --- ## 🪄 Available Tools ### Access Tokens

Manage access tokens for Storyblok API

- `retrieve_multiple_access_tokens`: List all access tokens - `create_access_token`: Create a new access token - `update_access_token`: Update an existing access token - `delete_access_token`: Delete an access token

### Activities

Manage or retrieve activity logs

- `retrieve_multiple_activities`: List activity logs

### Approvals

Manage approval workflows

- `retrieve_multiple_approvals`: List approvals - `create_approval`: Create a new approval - `update_approval`: Update an approval - `delete_approval`: Delete an approval

### Assets

Manage assets (upload, update, delete, list)

- `fetch_assets`: List assets with filtering - `get_asset`: Get a specific asset by ID - `delete_asset`: Delete an asset - `update_asset`: Update an asset - `delete_multiple_assets`: Delete multiple assets - `bulk_move_assets`: Move multiple assets - `bulk_restore_assets`: Restore multiple assets - `init_asset_upload`: Initialize asset upload - `complete_asset_upload`: Complete asset upload

### Assets Folder

Manage asset folders

- `retrieve_multiple_asset_folders`: List asset folders - `create_asset_folder`: Create a new asset folder - `update_asset_folder`: Update an asset folder - `delete_asset_folder`: Delete an asset folder

### Branch Deployments

Manage branch deployments

- `retrieve_multiple_branch_deployments`: List branch deployments - `create_branch_deployment`: Create a new branch deployment - `update_branch_deployment`: Update a branch deployment - `delete_branch_deployment`: Delete a branch deployment

### Collaborators

Manage collaborators in a space

- `retrieve_multiple_collaborators`: List collaborators - `add_collaborator`: Add a collaborator - `update_collaborator`: Update a collaborator - `remove_collaborator`: Remove a collaborator

### Components

Manage Storyblok components (CRUD, schema, etc.)

- `fetch_components`: List components with filtering - `get_component`: Get a specific component by ID - `create_component`: Create a new component - `update_component`: Update an existing component - `delete_component`: Delete a component - `get_component_usage`: Find stories using a component - `retrieve_component_versions`: List versions of a component - `retrieve_single_component_version`: Get a specific component version - `restore_component_version`: Restore a component to a previous version

### Components Folder

Manage folders for components

- `retrieve_multiple_component_folders`: List component folders - `create_component_folder`: Create a new component folder - `update_component_folder`: Update a component folder - `delete_component_folder`: Delete a component folder

### Datasource Entries

Manage entries in data sources

- `retrieve_multiple_datasource_entries`: List datasource entries - `create_datasource_entry`: Create a new datasource entry - `update_datasource_entry`: Update a datasource entry - `delete_datasource_entry`: Delete a datasource entry

### Data Sources

Manage data sources (CRUD, entries)

- `retrieve_multiple_data_sources`: List data sources - `create_data_source`: Create a new data source - `update_data_source`: Update a data source - `delete_data_source`: Delete a data source

### Discussions

Manage discussions and comments

- `retrieve_multiple_discussions`: List discussions - `retrieve_specific_discussion`: Get a specific discussion - `retrieve_idea_discussions_comments`: List idea discussion comments - `create_discussion`: Create a new discussion - `retrieve_my_discussions`: List my discussions

### Extensions

Manage Storyblok extensions

- `retrieve_all_extensions`: List all extensions - `retrieve_extension`: Get a specific extension - `create_extension`: Create a new extension - `update_extension`: Update an extension - `delete_extension`: Delete an extension - `retrieve_extension_settings`: Get extension settings - `retrieve_all_extension_settings`: List all extension settings

### Field Plugins

Manage custom field plugins

- `retrieve_field_plugins`: List field plugins - `retrieve_field_plugin`: Get a specific field plugin - `create_field_plugin`: Create a new field plugin - `update_field_plugin`: Update a field plugin - `delete_field_plugin`: Delete a field plugin

### Internal Tags

Manage internal tags for assets/stories

- `retrieve_multiple_internal_tags`: List internal tags - `create_internal_tag`: Create a new internal tag - `update_internal_tag`: Update an internal tag - `delete_internal_tag`: Delete an internal tag

### Meta

Meta tool: discover all available tools

- `list_tools`: List all available tools

### Ping

Health check and server status

- `ping`: Check server health

### Pipelines

Manage pipelines for content delivery

- `retrieve_multiple_branches`: List branches - `retrieve_single_branch`: Get a specific branch - `create_branch`: Create a new branch - `update_branch`: Update a branch - `delete_branch`: Delete a branch

### Presets

Manage field presets for components

- `retrieve_multiple_presets`: List field presets - `retrieve_single_preset`: Get a specific preset - `create_preset`: Create a new preset - `update_preset`: Update a preset - `delete_preset`: Delete a preset

### Releases

Manage releases (create, update, publish)

- `retrieve_multiple_releases`: List releases - `retrieve_single_release`: Get a specific release - `create_release`: Create a new release - `update_release`: Update a release - `delete_release`: Delete a release

### Scheduling Stories

Schedule stories for publishing

- `retrieve_multiple_story_schedules`: List story schedules - `retrieve_one_story_schedule`: Get a specific story schedule - `create_story_schedule`: Create a new story schedule - `update_story_schedule`: Update a story schedule - `delete_story_schedule`: Delete a story schedule

### Space

Manage Storyblok space settings and info

- `fetch_spaces`: List spaces - `get_space`: Get a specific space - `create_space`: Create a new space - `update_space`: Update a space - `duplicate_space`: Duplicate a space - `backup_space`: Backup a space - `delete_space`: Delete a space

### Space Roles

Manage roles and permissions in a space

- `fetch_space_roles`: List space roles - `get_space_role`: Get a specific space role - `create_space_role`: Create a new space role - `update_space_role`: Update a space role - `delete_space_role`: Delete a space role

### Stories

Manage stories (CRUD, bulk ops, validation)

- `fetch_stories`: List stories with filtering - `get_story`: Get a specific story by ID - `create_story`: Create a new story - `update_story`: Update an existing story - `delete_story`: Delete a story - `publish_story`: Publish a story - `unpublish_story`: Unpublish a story - `get_story_versions`: List versions of a story - `restore_story`: Restore a story to a previous version - `validate_story_content`: Validate story content - `debug_story_access`: Debug access for a story - `bulk_publish_stories`: Publish multiple stories - `bulk_delete_stories`: Delete multiple stories - `bulk_update_stories`: Update multiple stories - `bulk_create_stories`: Create multiple stories - `get_unpublished_dependencies`: List unpublished dependencies - `ai_translate_story`: AI-powered translation for a story - `compare_story_versions`: Compare two versions of a story

### Tags

Manage tags (CRUD, bulk association)

- `retrieve_multiple_tags`: List tags - `create_tag`: Create a new tag - `update_tag`: Update a tag - `delete_tag`: Delete a tag - `tag_bulk_association`: Add tags to multiple stories

### Tasks

Manage tasks (CRUD, webhooks, automation)

- `retrieve_multiple_tasks`: List tasks - `retrieve_single_task`: Get a specific task - `create_task`: Create a new task - `update_task`: Update a task - `delete_task`: Delete a task

### Webhooks

Manage webhooks (CRUD, trigger)

- `retrieve_multiple_webhooks`: List webhooks - `retrieve_single_webhook`: Get a specific webhook - `add_webhook`: Add a new webhook - `update_webhook`: Update a webhook - `delete_webhook`: Delete a webhook

### Workflows

Manage workflows and workflow stages

- `retrieve_multiple_workflows`: List workflows - `retrieve_single_workflow`: Get a specific workflow - `create_workflow`: Create a new workflow - `update_workflow`: Update a workflow - `duplicate_workflow`: Duplicate a workflow - `delete_workflow`: Delete a workflow

### Workflow Stage

Manage individual workflow stages

- `retrieve_multiple_workflow_stages`: List workflow stages - `retrieve_single_workflow_stage`: Get a specific workflow stage - `create_workflow_stage`: Create a new workflow stage - `update_workflow_stage`: Update a workflow stage - `delete_workflow_stage`: Delete a workflow stage

### Workflow Stage Changes

Track and manage workflow stage changes

- `retrieve_multiple_workflow_stage_changes`: List workflow stage changes - `create_workflow_stage_change`: Create a workflow stage change

## ⚡️ Quickstart 1. **Clone the repo** ```sh git clone cd storyblok-mcp-server ``` 2. **Install dependencies** ```sh pip install -r requirements.txt ``` 3. **Configure your environment** - Copy `.env.example` to `.env` and fill in your Storyblok credentials: ``` STORYBLOK_SPACE_ID=your_space_id STORYBLOK_MANAGEMENT_TOKEN=your_management_token STORYBLOK_DEFAULT_PUBLIC_TOKEN=your_public_token ``` 4. **MCP Client Configuration** - To use this server with Claude or any MCP client, copy the following into your `claude_desktop_config.json`: ```json { "mcpServers": { "storyblok": { "command": "uv", "args": [ "run", "--with", "mcp", "mcp", "run", "C:\\path\\to\\storyblok-mcp-server\\server.py" ], "env": { "STORYBLOK_SPACE_ID": "your_space_id", "STORYBLOK_MANAGEMENT_TOKEN": "your_management_token", "STORYBLOK_DEFAULT_PUBLIC_TOKEN": "your_public_token" } } } } ``` - Paste this config into your Claude or MCP client to connect instantly. > [!NOTE] > Make sure you have installed `uv` on your system Restart your Claude Desktop and chek the tools. It will show total number tools available if you connected successfully. ![Claude Desktop](./assets/claude.png) 5. **Run and Test Locally** - You can also run and test the server locally using MCP Inspector: ```sh mcp run server.py ``` ![mcp inspector](./assets/inspector.png) ## Example Questions > [!TIP] > Here are some natural language queries you can try with your MCP Client. * "Show me all stories from storyblok" * "Give me details about Home story" * "Create a new story with any content" * "Publish Home story" --- ## 🧑‍💻 Contributing We welcome contributions! To get started: 1. **Fork the repo** and create your branch from `master`. 2. **Add or improve a tool** in the `tools/` directory. 3. **Write clear docstrings** and keep code modular. 4. **Use MCP Inspector** for debugging 5. **Open a pull request** with a clear description of your changes. ### Coding Guidelines - Use type hints and docstrings for all functions and classes. - Keep each tool focused on a single Storyblok resource. - Handle API errors gracefully and return informative messages. - Keep the `.env` file out of version control. --- ## 🤝 Credits Built with [Storyblok](https://www.storyblok.com/) and [FastMCP](https://gofastmcp.com/getting-started/welcome). --- ## 📄 License MIT License. See [LICENSE](LICENSE) for details. --- ## 💬 Questions & Support - For issues, open a GitHub issue. - For feature requests, open a discussion or PR. - For Storyblok API docs, see [Storyblok API Reference](https://www.storyblok.com/docs/api/management). --- _Built with 💙 by [Kiran](https://github.com/Kiran1689)_