This is a submission for the Storyblok Challenge
What I Built
I built a modular, extensible Storyblok MCP Server that allows seamless integration between AI assistants and the full capabilities of the Storyblok Management API.
This Storyblok MCP (Model Context Protocol) Server enables your AI assistants to directly access and manage every aspect of a Storyblok spaces, stories, components, assets, workflows, and more...
This project aims to remove the barrier between conversational interfaces and content operations, enabling developers, marketers, and content creators to interact with Storyblok hands-free.
I’ve implemented 155+ MCP tools, covering nearly all endpoints in the Storyblok Management API.
With over 155+ mcp tools Your AI assistant can now:
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.
🔧 No manual API definitions needed
🎯 All operations are abstracted into MCP tools
Why This Matters? 🤔
👨💻 For Developers: Instantly expose all Storyblok operations as AI tools, no more writing repetitive API code.
⚡ For Teams: Empower marketers, editors, and non-technical users to manage content with natural language.
💪 For AI Builders: Use this as a plug-and-play backend for any LLM or agent that supports tool calling.
Demo
Code Repository:
Checkout the repo for detailed instructions and to see all available tools. You can view the full list of tools directly in the Tools Section of the README. (⭐ to show your support 🙂)
Kiran1689
/
storyblok-mcp-server
A modular, extensible MCP Server for managing Storyblok spaces, stories, components, assets, workflows, and more via the Model Context Protocol (MCP).
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…
Demo Video
Watch the Full Demo Video here👇
I have only covered
storiestools in the video for demo purpose. Feel free to use it however you want after connecting to MCP server.
⚡️ Quickstart
- Clone the repo
git clone https://github.com/Kiran1689/storyblok-mcp-server
cd storyblok-mcp-server
- Install dependencies
pip install -r requirements.txt
-
Configure your environment
Copy
.env.exampleto.envand fill in your Storyblok credentials:
SORYBLOK_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
uvon your system
Restart your Claude Desktop and check the tools. If connected, you’ll see the total number of tools available.
- Run and Test Locally You can also run and test the server locally using MCP Inspector:
mcp run server.py
Tech Stack
I used:
- Python (HTTPX, AsyncIO)
- MCP Python SDK
- FastMCP (for defining AI tools)
- Storyblok Management API
Project Structure 📂
storyblok_mcp/
├── config.py # Project configuration (API keys, settings, etc.)
├── pyproject.toml # Python project metadata and dependencies
├── server.py # Main server entrypoint (FastAPI/MCP server)
├── tools/
│ ├── components.py # Tools for Storyblok components
│ ├── space.py # Tools for Storyblok spaces
│ ├── stories.py # Tools for Storyblok stories
│ ├── access_tokens.py # Tools for Storyblok access tokens
│ ├── assets.py # Tools for Storyblok assets
│ ├── tags.py # Tools for Storyblok tags
│ ├── tasks.py # Tools for Storyblok tasks
│ ├── releases.py # Tools for Storyblok releases
│ └── ... # All other tool files
└── utils/
└── api.py # API helpers (request building, error handling)
How I Got Started 💭
Like many devs, I also started with a simple question:
How can I make Storyblok’s powerful API accessible to AI assistants, so that users don't need to manually handle anything?
My References & Research 💡
MCP Official Documentation:
This was my starting point. I learned how to define tools, register them, and build a custom server from scratch.Storyblok Management API Docs:
I mapped every endpoint to a tool, making sure nothing was left out.FastMCP GitHub:
I studied real-world examples to understand best practices for tool registration and async support. (Lot of Medium articles💡)MCP Inspector:
This tool was a lifesaver for debugging and testing my server.
Designing for AI and Humans
I wanted this project to be more than just a wrapper. My goal was to make it:
- AI-native: Every tool is self-describing, with clear parameters, body and docstrings.
- Human-friendly: Non-technical users can use it via chat, while devs can extend it easily.
Example: Registering a Tool
@mcp.tool()
async def create_story(
name: str,
slug: str,
content: Dict[str, Any],
parent_id: Optional[int] = None,
group_id: Optional[str] = None,
sort_by_date: Optional[str] = None,
is_folder: bool = False,
default_root: Optional[str] = None,
disable_fe_editor: Optional[bool] = None,
is_startpage: bool = False,
meta_data: Optional[Dict[str, Any]] = None,
pinned: Optional[bool] = None,
translated_slugs_attributes: Optional[List[Dict[str, Any]]] = None,
position: Optional[int] = None,
publish: Optional[bool] = False,
release_id: Optional[int] = None,
) -> Any:
"""
Creates a new Storyblok story.
Supports all documented fields including publishing.
"""
try:
# Construct story object with optional fields
story_payload: Dict[str, Any] = {
"name": name,
"slug": slug,
"content": content,
}
# Only include optional properties if provided
for key, val in {
"parent_id": parent_id,
"group_id": group_id,
"sort_by_date": sort_by_date,
"is_folder": is_folder,
"default_root": default_root,
"disable_fe_editor": disable_fe_editor,
"is_startpage": is_startpage,
"meta_data": meta_data,
"pinned": pinned,
"translated_slugs_attributes": translated_slugs_attributes,
"position": position,
"release_id": release_id
}.items():
if val is not None:
story_payload[key] = val
# Prepare request payload
payload = {"story": story_payload}
if publish:
payload["publish"] = 1
url = build_management_url("/stories")
resp = await client.post(
url,
headers=get_management_headers(),
json=payload
)
return _handle_response(resp, url)
except APIError as e:
return {"isError": True, "content": [{"type": "text", "text": str(e)}]}
This pattern is repeated for every resource, making the codebase consistent and easy to expand. 😉
Managing 150+ Endpoints 😵💫
Covering the entire Storyblok Management API was no small feat.🥲
- I broke the project into modules: one file per resource (stories, components, assets, etc.).
- Each module registers its own tools, making the codebase scalable and maintainable.(In future if we add more resources)
- I implemented a meta-tool for tool discovery, so AI agents can see what’s available at runtime.
Handling Edge Cases:
Some endpoints required special handling (e.g., bulk operations, versioning). I used Python’s async features and careful error handling to keep everything clean.
How I Used Storyblok
Storyblok's Management API is the backbone of this entire project. Every endpoint is mapped to an AI tool, so you never have to deal with tokens, URLs, or payloads manually.
The Resources I covered from Storyblok's Management API 👇
| 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 |
AI Integration
This project is built to be AI-native. Any LLM or AI agent that supports tool calling can use this server to call the tools automatically.
Each MCP tool is designed so an AI agent can:
Understand its purpose via tool descriptions.
Call it with minimal inputs.
I tested the server with Claude Desktop and the Claude Sonnet 4 model, the results were accurate and fast. You can see this in the demo video or try it yourself.
Making It Easy for Everyone
One of my main goals was to make this server accessible to all, whether you’re a developer or a marketer. The consistent tool interface, clear documentation, and plug-and-play setup mean you can get started in minutes, not days. And if you want to build something new, the modular codebase makes it easy to add your own tools or customize existing ones.
Real-World Use Cases
Automated Content Workflows:
Let your AI assistant publish, update, or archive content on a schedule or in response to business events.Conversational Content Management:
Non-technical users can ask for reports, create new stories, or update assets—all via chat.Bulk Operations:
Instantly update, delete, or migrate hundreds of stories or assets with a single command.
Learnings and Takeaways
To be honest, I’ve always wanted to build a custom MCP server that’s genuinely useful for others. This challenge gave me the push to do it!
- Learned how to structure AI tools using FastMCP for real-world use.
- Discovered MCP Inspector for debugging and testing MCP servers. It was super helpful!
- Overcame the challenge of managing 150+ endpoints by building a uniform abstraction layer.
Building this server was a creative and technical challenge, but the result is a tool that makes advanced content management accessible to everyone (developers, marketers, and AI agents alike).
Thanks for this opportunity🫶
If you have questions or want to contribute, check out the repo or open an issue.
Top comments (25)
This is really cool! Thanks for sharing
Thank you!!
Awesome Kiran
Thanks Nick :)
Interesting to read, amazing work
Thank you Nadeem!
Awesome🔥
Thank you Prajwal :)
Is Claude free? Or is there a free slow tier?
It has both free and paid version same as gpt..
Great 👍
Thank You Mohan!
You nailed it here 🔥
Thank you Neha!
This is really next level - 155+ tools abstracted for AI is super impressive. Have you tried this with agents outside of Claude or hooked it into custom chat interfaces yet?
Thanks!!
I tried it with Claude, but you can try it with any LLMs or AI agents that supports tool calling 👍
Pretty cool, I've enjoyed all of the research you've put into this project, it adds up
Thanks Nathan!
Amazing work! Super impressed by how you integrated AI with Storyblock so seamlessly. 155+ tools is no joke huge impact for both devs and content teams.
Thank you Sanjay :)
Some comments may only be visible to logged-in visitors. Sign in to view all comments.