Storyblok Mcp Server

它能做什么？

借助 Storyblok MCP 服务，AI 助手可以：

• 创建 - 创建故事、组件、资源、数据源、标签、发布版本、工作流等。
• 读取 - 读取所有故事、组件、资源、数据源、标签、发布版本、工作流等。
• 更新 - 更新现有或新的故事、组件、资源、数据源、标签、发布版本、工作流等。
• 删除 - 删除指定或全部故事、组件、资源、数据源、标签、发布版本、工作流等。

---

🚀 功能

• 全面管理 Storyblok：对故事、组件、资源、数据源、标签、发布版本、工作流等执行 CRUD 操作。（涵盖所有功能）
• 模块化工具：每种 Storyblok 资源都由独立的工具模块管理，便于扩展和维护。
• 元工具：在运行时发现所有可用工具及其描述。
• 异步且快速：基于 httpx 和 FastMCP 构建，性能出色。
• 基于环境的配置：通过 .env 安全管理令牌和空间 ID。
• 批量操作：一次高效更新、删除或发布多个资源。

---

📦 项目结构

├── 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 覆盖范围

资源	描述
访问令牌	管理 Storyblok API 的访问令牌
活动	管理或检索活动日志
审批	管理审批工作流
资源	管理资源（上传、更新、删除、列出）
资源文件夹	管理资源文件夹
分支部署	管理分支部署
协作者	管理空间中的协作者
组件	管理 Storyblok 组件（CRUD、架构等）
组件文件夹	管理组件文件夹
数据源条目	管理数据源中的条目
数据源	管理数据源（CRUD、条目）
讨论	管理讨论和评论
扩展	管理 Storyblok 扩展
字段插件	管理自定义字段插件
内部标签	管理资源/故事的内部标签
Meta	Meta 工具：发现所有可用工具
Ping	健康检查和服务状态
管道	管理内容交付管道
预设	管理组件的字段预设
发布	管理发布（创建、更新、发布）
故事排期	安排故事发布
空间	管理 Storyblok 空间设置和信息
空间角色	管理空间中的角色和权限
故事	管理故事（CRUD、批量操作、验证）
标签	管理标签（CRUD、批量关联）
任务	管理任务（CRUD、Webhook、自动化）
Webhook	管理 Webhook（CRUD、触发）
工作流	管理工作流和工作流阶段
工作流阶段	管理单个工作流阶段
工作流阶段变更	跟踪和管理工作流阶段变更

---

🪄 可用工具

访问令牌

管理 Storyblok API 的访问令牌

• retrieve_multiple_access_tokens：列出所有访问令牌
• create_access_token：创建新的访问令牌
• update_access_token：更新现有访问令牌
• delete_access_token：删除访问令牌

活动

管理或检索活动日志

• retrieve_multiple_activities：列出活动日志

审批

管理审批工作流

• retrieve_multiple_approvals：列出审批
• create_approval：创建新的审批
• update_approval：更新审批
• delete_approval：删除审批

资源

管理资源（上传、更新、删除、列出）

• fetch_assets：按筛选条件列出资源
• get_asset：按 ID 获取指定资源
• delete_asset：删除资源
• update_asset：更新资源
• delete_multiple_assets：删除多个资源
• bulk_move_assets：移动多个资源
• bulk_restore_assets：恢复多个资源
• init_asset_upload：初始化资源上传
• complete_asset_upload：完成资源上传

### 资源文件夹

管理资源文件夹

• retrieve_multiple_asset_folders：列出资源文件夹
• create_asset_folder：创建新的资源文件夹
• update_asset_folder：更新资源文件夹
• delete_asset_folder：删除资源文件夹

分支部署

管理分支部署

• retrieve_multiple_branch_deployments：列出分支部署
• create_branch_deployment：创建新的分支部署
• update_branch_deployment：更新分支部署
• delete_branch_deployment：删除分支部署

协作者

管理空间中的协作者

• retrieve_multiple_collaborators：列出协作者
• add_collaborator：添加协作者
• update_collaborator：更新协作者
• remove_collaborator：移除协作者

组件

管理 Storyblok 组件（CRUD、架构等）

• fetch_components：列出组件并进行筛选
• get_component：按 ID 获取指定组件
• create_component：创建新组件
• update_component：更新现有组件
• delete_component：删除组件
• get_component_usage：查找使用组件的故事
• retrieve_component_versions：列出组件版本
• retrieve_single_component_version：获取指定组件版本
• restore_component_version：将组件还原到先前的版本

组件文件夹

管理组件文件夹

• retrieve_multiple_component_folders：列出组件文件夹
• create_component_folder：创建新的组件文件夹
• update_component_folder：更新组件文件夹
• delete_component_folder：删除组件文件夹

数据源条目

管理数据源中的条目

• retrieve_multiple_datasource_entries：列出数据源条目
• create_datasource_entry：创建新的数据源条目
• update_datasource_entry：更新数据源条目
• delete_datasource_entry：删除数据源条目

数据源

管理数据源（CRUD、条目）

• retrieve_multiple_data_sources：列出数据源
• create_data_source：创建新的数据源
• update_data_source：更新数据源
• delete_data_source：删除数据源

讨论

管理讨论和评论

• retrieve_multiple_discussions：列出讨论
• retrieve_specific_discussion：获取指定讨论
• retrieve_idea_discussions_comments：列出创意讨论评论
• create_discussion：创建新讨论
• retrieve_my_discussions：列出我的讨论

扩展

管理 Storyblok 扩展

• retrieve_all_extensions：列出所有扩展
• retrieve_extension：获取指定扩展
• create_extension：创建新扩展
• update_extension：更新扩展
• delete_extension：删除扩展
• retrieve_extension_settings：获取扩展设置
• retrieve_all_extension_settings：列出所有扩展设置

字段插件

管理自定义字段插件

• retrieve_field_plugins：列出字段插件
• retrieve_field_plugin：获取指定字段插件
• create_field_plugin：创建新的字段插件
• update_field_plugin：更新字段插件
• delete_field_plugin：删除字段插件

内部标签

管理资源/故事的内部标签

• retrieve_multiple_internal_tags：列出内部标签
• create_internal_tag：创建新的内部标签
• update_internal_tag：更新内部标签
• delete_internal_tag：删除内部标签

### Meta

Meta 工具：发现所有可用工具

• list_tools：列出所有可用工具

Ping

健康检查与服务状态

• ping：检查服务健康状态

Pipelines

管理内容交付管道

• retrieve_multiple_branches：列出分支
• retrieve_single_branch：获取指定分支
• create_branch：创建新分支
• update_branch：更新分支
• delete_branch：删除分支

Presets

管理组件的字段预设

• retrieve_multiple_presets：列出字段预设
• retrieve_single_preset：获取指定预设
• create_preset：创建新预设
• update_preset：更新预设
• delete_preset：删除预设

Releases

管理发布（创建、更新、发布）

• retrieve_multiple_releases：列出发布
• retrieve_single_release：获取指定发布
• create_release：创建新发布
• update_release：更新发布
• delete_release：删除发布

Scheduling Stories

安排故事发布

• retrieve_multiple_story_schedules：列出故事发布计划
• retrieve_one_story_schedule：获取指定故事发布计划
• create_story_schedule：创建新的故事发布计划
• update_story_schedule：更新故事发布计划
• delete_story_schedule：删除故事发布计划

Space

管理 Storyblok 空间设置和信息

• fetch_spaces：列出空间
• get_space：获取指定空间
• create_space：创建新空间
• update_space：更新空间
• duplicate_space：复制空间
• backup_space：备份空间
• delete_space：删除空间

Space Roles

管理空间中的角色和权限

• fetch_space_roles：列出空间角色
• get_space_role：获取指定空间角色
• create_space_role：创建新空间角色
• update_space_role：更新空间角色
• delete_space_role：删除空间角色

Stories

管理故事（CRUD、批量操作、验证）

• fetch_stories：按条件筛选并列出故事
• get_story：按 ID 获取指定故事
• create_story：创建新故事
• update_story：更新现有故事
• delete_story：删除故事
• publish_story：发布故事
• unpublish_story：取消发布故事
• get_story_versions：列出故事的版本
• restore_story：将故事恢复到之前的版本
• validate_story_content：验证故事内容
• debug_story_access：调试故事的访问权限
• bulk_publish_stories：发布多个故事
• bulk_delete_stories：删除多个故事
• bulk_update_stories：更新多个故事
• bulk_create_stories：创建多个故事
• get_unpublished_dependencies：列出尚未发布的依赖项
• ai_translate_story：使用 AI 翻译故事
• compare_story_versions：比较两个版本的故事

Tags

管理标签（CRUD、批量关联）

• retrieve_multiple_tags：列出标签
• create_tag：创建新标签
• update_tag：更新标签
• delete_tag：删除标签
• tag_bulk_association：为多个故事添加标签

Tasks

管理任务（CRUD、Webhook、自动化）

• retrieve_multiple_tasks：列出任务
• retrieve_single_task：获取指定任务
• create_task：创建新任务
• update_task：更新任务
• delete_task：删除任务

### Webhooks

管理 Webhook（CRUD、触发）

• retrieve_multiple_webhooks：列出 Webhook
• retrieve_single_webhook：获取特定 Webhook
• add_webhook：添加新的 Webhook
• update_webhook：更新 Webhook
• delete_webhook：删除 Webhook

Workflows

管理工作流和工作流阶段

• retrieve_multiple_workflows：列出工作流
• retrieve_single_workflow：获取特定工作流
• create_workflow：创建新的工作流
• update_workflow：更新工作流
• duplicate_workflow：复制工作流
• delete_workflow：删除工作流

Workflow Stage

管理单个工作流阶段

• retrieve_multiple_workflow_stages：列出工作流阶段
• retrieve_single_workflow_stage：获取特定工作流阶段
• create_workflow_stage：创建新的工作流阶段
• update_workflow_stage：更新工作流阶段
• delete_workflow_stage：删除工作流阶段

Workflow Stage Changes

跟踪和管理工作流阶段变更

• retrieve_multiple_workflow_stage_changes：列出工作流阶段变更
• create_workflow_stage_change：创建工作流阶段变更

⚡️ 快速入门

1. 克隆仓库

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

2. 安装依赖项

   pip install -r requirements.txt
   

3. 配置环境

   • 将 .env.example 复制为 .env，并填写 Storyblok 凭据：

     STORYBLOK_SPACE_ID=your_space_id
     STORYBLOK_MANAGEMENT_TOKEN=your_management_token
     STORYBLOK_DEFAULT_PUBLIC_TOKEN=your_public_token
     

4. MCP 客户端配置

   • 要将此服务与 Claude 或任何 MCP 客户端搭配使用，请将以下内容复制到 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"
            }
        }
    }
}

• 将此配置粘贴到 Claude 或 MCP 客户端中，即可立即连接。

说明

请确保已在系统上安装 uv

重启 Claude Desktop 并检查工具。如果连接成功，界面会显示可用工具的总数。

5. 在本地运行和测试
   • 你也可以使用 MCP Inspector 在本地运行和测试服务：

   mcp run server.py
   

示例问题

提示

以下是一些可以在 MCP 客户端中尝试的自然语言查询。

• "Show me all stories from storyblok"
• "Give me details about Home story"
• "Create a new story with any content"
• "Publish Home story"

---

🧑‍💻 参与贡献

欢迎贡献！开始参与：

1. 复刻仓库，并从 master 创建分支。
2. 在 tools/ 目录中添加或改进工具。
3. 编写清晰的文档字符串，并保持代码模块化。
4. 使用 MCP Inspector 进行调试
5. 提交拉取请求，并清楚描述所做的更改。

编码指南

• 为所有函数和类使用类型提示并编写文档字符串。
• 每个工具只专注于一个 Storyblok 资源。
• 妥善处理 API 错误，并返回清晰有用的消息。
• 不要将 .env 文件纳入版本控制。

---

🤝 致谢

基于 Storyblok 和 FastMCP 构建。

---

📄 许可证

MIT 许可证。详情请参阅 LICENSE。

---

💬 问题与支持

• 遇到问题，请提交 GitHub issue。
• 有功能请求，请发起讨论或提交 PR。
• Storyblok API 文档请参阅 Storyblok API Reference。

---

由 Kiran 用 💙 构建