README.md•19 kB
<picture>
<source media="(prefers-color-scheme: dark)" srcset="./assets/banner_dark.png">
<source media="(prefers-color-scheme: light)" srcset="./assets/banner_white.png">
<img align="center" alt="banner" src="./assets/banner_white.png">
</picture>
<div align="center">
# 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.
<a href="https://www.storyblok.com/docs/api/management/getting-started" target="_blank" rel="noopener noreferrer"><img src="https://img.shields.io/badge/documentation-storyblok-blue" alt="documentation" /></a>
<a href="https://reactjs.org/"><img alt="Made With React" src="https://img.shields.io/badge/made%20with-python-yellow?style=flat" /></a>
<a href="https://github.com/Kiran1689" target="_blank" rel="noopener noreferrer"><img src="https://img.shields.io/badge/built_with-love-red" alt="built with love badge" /></a>
<img src="https://img.shields.io/badge/built_for-developers-dcd4fc" alt="built for developers badge" /></a>
<img src="https://img.shields.io/badge/built_for-marketers-bce4fb" alt="built for marketers badge" /></a>
</div>
## 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
<details>
<summary>Manage access tokens for Storyblok API</summary>
- `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
</details>
### Activities
<details>
<summary>Manage or retrieve activity logs</summary>
- `retrieve_multiple_activities`: List activity logs
</details>
### Approvals
<details>
<summary>Manage approval workflows</summary>
- `retrieve_multiple_approvals`: List approvals
- `create_approval`: Create a new approval
- `update_approval`: Update an approval
- `delete_approval`: Delete an approval
</details>
### Assets
<details>
<summary>Manage assets (upload, update, delete, list)</summary>
- `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
</details>
### Assets Folder
<details>
<summary>Manage asset folders</summary>
- `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
</details>
### Branch Deployments
<details>
<summary>Manage branch deployments</summary>
- `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
</details>
### Collaborators
<details>
<summary>Manage collaborators in a space</summary>
- `retrieve_multiple_collaborators`: List collaborators
- `add_collaborator`: Add a collaborator
- `update_collaborator`: Update a collaborator
- `remove_collaborator`: Remove a collaborator
</details>
### Components
<details>
<summary>Manage Storyblok components (CRUD, schema, etc.)</summary>
- `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
</details>
### Components Folder
<details>
<summary>Manage folders for components</summary>
- `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
</details>
### Datasource Entries
<details>
<summary>Manage entries in data sources</summary>
- `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
</details>
### Data Sources
<details>
<summary>Manage data sources (CRUD, entries)</summary>
- `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
</details>
### Discussions
<details>
<summary>Manage discussions and comments</summary>
- `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
</details>
### Extensions
<details>
<summary>Manage Storyblok extensions</summary>
- `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
</details>
### Field Plugins
<details>
<summary>Manage custom field plugins</summary>
- `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
</details>
### Internal Tags
<details>
<summary>Manage internal tags for assets/stories</summary>
- `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
</details>
### Meta
<details>
<summary>Meta tool: discover all available tools</summary>
- `list_tools`: List all available tools
</details>
### Ping
<details>
<summary>Health check and server status</summary>
- `ping`: Check server health
</details>
### Pipelines
<details>
<summary>Manage pipelines for content delivery</summary>
- `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
</details>
### Presets
<details>
<summary>Manage field presets for components</summary>
- `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
</details>
### Releases
<details>
<summary>Manage releases (create, update, publish)</summary>
- `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
</details>
### Scheduling Stories
<details>
<summary>Schedule stories for publishing</summary>
- `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
</details>
### Space
<details>
<summary>Manage Storyblok space settings and info</summary>
- `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
</details>
### Space Roles
<details>
<summary>Manage roles and permissions in a space</summary>
- `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
</details>
### Stories
<details>
<summary>Manage stories (CRUD, bulk ops, validation)</summary>
- `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
</details>
### Tags
<details>
<summary>Manage tags (CRUD, bulk association)</summary>
- `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
</details>
### Tasks
<details>
<summary>Manage tasks (CRUD, webhooks, automation)</summary>
- `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
</details>
### Webhooks
<details>
<summary>Manage webhooks (CRUD, trigger)</summary>
- `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
</details>
### Workflows
<details>
<summary>Manage workflows and workflow stages</summary>
- `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
</details>
### Workflow Stage
<details>
<summary>Manage individual workflow stages</summary>
- `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
</details>
### Workflow Stage Changes
<details>
<summary>Track and manage workflow stage changes</summary>
- `retrieve_multiple_workflow_stage_changes`: List workflow stage changes
- `create_workflow_stage_change`: Create a workflow stage change
</details>
## ⚡️ Quickstart
1. **Clone the repo**
```sh
git clone <your-repo-url>
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.
5. **Run and Test Locally**
- You can also run and test the server locally using MCP Inspector:
```sh
mcp run server.py
```
## 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)_