README - storyblok-mcp-server by kiran1689

Storyblok MCP Server 🚀

The Storyblok MCP (Model Context Protocol) 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

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

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

Clone the repo

git clone <your-repo-url>
cd storyblok-mcp-server

Install dependencies
```
pip install -r requirements.txt
```

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

MCP Client Configuration
- To use this server with Claude or any MCP client, copy the following into your claude_desktop_config.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.

Run and Test Locally
- You can also run and test the server locally using MCP Inspector:
```
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:

Fork the repo and create your branch from master.
Add or improve a tool in the tools/ directory.
Write clear docstrings and keep code modular.
Use MCP Inspector for debugging
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 and FastMCP.

📄 License

MIT License. See 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.

Built with 💙 by Kiran