DEV Community

Cover image for 🔥Storyblok MCP Server: Let AI Agents Manage Your Content 🤖
Kiran Naragund
Kiran Naragund Subscriber

Posted on • Edited on

🔥Storyblok MCP Server: Let AI Agents Manage Your Content 🤖

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 🙂)

GitHub logo 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).

banner

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.

documentation Made With React built with love badge built for developers badge built for marketers badge

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 stories tools 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
Enter fullscreen mode Exit fullscreen mode
  • Install dependencies
pip install -r requirements.txt
Enter fullscreen mode Exit fullscreen mode
  • Configure your environment Copy .env.example to .env and fill in your Storyblok credentials:
SORYBLOK_SPACE_ID=your_space_id
STORYBLOK_MANAGEMENT_TOKEN=your_management_token
STORYBLOK_DEFAULT_PUBLIC_TOKEN=your_public_token
Enter fullscreen mode Exit fullscreen mode
  • 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"
            }
        }
    }
}
Enter fullscreen mode Exit fullscreen mode
  • 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 check the tools. If connected, you’ll see the total number of tools available.

claude

  • Run and Test Locally You can also run and test the server locally using MCP Inspector:
mcp run server.py
Enter fullscreen mode Exit fullscreen mode

MCP Inspector

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)
Enter fullscreen mode Exit fullscreen mode

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)}]}
Enter fullscreen mode Exit fullscreen mode

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)

Collapse
 
ansellmaximilian profile image
Ansell Maximilian

This is really cool! Thanks for sharing

Collapse
 
dev_kiran profile image
Kiran Naragund

Thank you!!

Collapse
 
codienick profile image
CodewithNick

Awesome Kiran

Collapse
 
dev_kiran profile image
Kiran Naragund

Thanks Nick :)

Collapse
 
nadeem_zia_257af7e986ffc6 profile image
nadeem zia

Interesting to read, amazing work

Collapse
 
dev_kiran profile image
Kiran Naragund

Thank you Nadeem!

Collapse
 
prajwalys2001 profile image
Prajwal

Awesome🔥

Collapse
 
dev_kiran profile image
Kiran Naragund

Thank you Prajwal :)

Collapse
 
avisheks profile image
Avishek sharma

Is Claude free? Or is there a free slow tier?

Collapse
 
dev_kiran profile image
Kiran Naragund

It has both free and paid version same as gpt..

Collapse
 
devmohan profile image
Mohan

Great 👍

Collapse
 
dev_kiran profile image
Kiran Naragund

Thank You Mohan!

Collapse
 
neha_varad_ profile image
Neha Varad

I’ve implemented 155+ MCP tools, covering nearly all endpoints in the Storyblok Management API.

You nailed it here 🔥

Collapse
 
dev_kiran profile image
Kiran Naragund

Thank you Neha!

Collapse
 
dotallio profile image
Dotallio

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?

Collapse
 
dev_kiran profile image
Kiran Naragund

Thanks!!
I tried it with Claude, but you can try it with any LLMs or AI agents that supports tool calling 👍

Collapse
 
nathan_tarbert profile image
Nathan Tarbert

Pretty cool, I've enjoyed all of the research you've put into this project, it adds up

Collapse
 
dev_kiran profile image
Kiran Naragund

Thanks Nathan!

Collapse
 
devmakasana profile image
Sanjay M.

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.

Collapse
 
dev_kiran profile image
Kiran Naragund

Thank you Sanjay :)

Some comments may only be visible to logged-in visitors. Sign in to view all comments.