kiran1689/storyblok-mcp-server

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

---

🪄 Available Tools

Access Tokens

Activities

Approvals

Assets

Assets Folder

Branch Deployments

Collaborators

Components

Components Folder

Datasource Entries

Data Sources

Discussions

Extensions

Field Plugins

Internal Tags

Meta

Ping

Pipelines

Presets

Releases

Scheduling Stories

Space

Space Roles

Stories

Tags

Tasks

Webhooks

Workflows

Workflow Stage

Workflow Stage Changes

⚡️ Quickstart

1. Clone the repo

   git clone 
   cd storyblok-mcp-server
   

2. Install dependencies

   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:

{
    "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:

   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 and FastMCP.

---

📄 License

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

---

Built with 💙 by Kiran