Contentful MCP Server

Contentful MCP 服务

声明

这是一个由社区驱动的服务！Contentful 已发布官方服务，你可以在此处找到。

一个与 Contentful 内容管理 API 集成的 MCP 服务，可提供全面的内容管理能力。

• 请注意 *；如果你对代码不感兴趣，只想在 Claude Desktop（或任何能够使用 MCP 服务的其他工具）中使用此 MCP，则无需克隆此仓库，只需在 Claude Desktop 中进行设置即可。安装说明请参阅“在 Claude Desktop 中使用”一节。

功能

• 内容管理：对条目和资源执行完整的 CRUD 操作
• 评论管理：创建、检索和管理条目评论，支持纯文本和富文本格式，包括串接对话
• 空间管理：创建、更新和管理空间与环境
• 内容类型：管理内容类型定义
• 本地化：支持多种语言区域设置
• 发布：控制内容发布工作流
• 批量操作：对多个条目和资源执行批量发布、取消发布和验证
• 智能分页：列表操作每次请求最多返回 3 个条目，以防止上下文窗口溢出，并内置分页支持

分页

为防止大模型的上下文窗口溢出，列表操作（例如 search_entries 和 list_assets）每次请求最多返回 3 个条目。每个响应包含：

• 可用条目的总数
• 当前页的条目（最多 3 个）
• 剩余条目数
• 下一页的 skip 值
• 提示大模型提供获取更多条目的选项

该分页系统让大模型能够高效处理大型数据集，同时保持在上下文窗口限制内。

批量操作

批量操作功能可高效地同时管理多个内容项：

• 异步处理：操作以异步方式运行，并提供状态更新
• 高效内容管理：通过一次 API 调用处理多个条目或资源
• 状态跟踪：通过成功和失败计数监控进度
• 资源优化：减少 API 调用，提升批量操作的性能

这些批量操作工具适用于内容迁移、大规模更新或批量发布工作流。

工具

条目管理

• search_entries：使用查询参数搜索条目
• create_entry：创建新条目
• get_entry：检索现有条目
• update_entry：更新条目字段
• delete_entry：删除条目
• publish_entry：发布条目
• unpublish_entry：取消发布条目

评论管理

• get_comments：检索条目的评论，并按状态（active、resolved、all）筛选
• create_comment：在条目上创建新评论，支持纯文本和富文本格式。提供父评论 ID 即可回复现有评论，从而支持串接对话
• get_single_comment：根据 ID 检索条目的特定评论
• delete_comment：从条目中删除特定评论
• update_comment：更新现有评论的正文内容或状态

线程化评论

评论支持线程功能，可用于组织结构化对话，并绕过 512 个字符的限制：

• 回复评论：在 create_comment 中使用 parent 参数，回复现有评论
• 线程化对话：通过回复特定评论来构建对话树
• 延长讨论：通过创建线程回复来绕过 512 个字符的限制，继续发送较长消息
• 对话上下文：通过将相关评论组织到线程中，保持讨论的上下文

使用示例：

1. 创建主评论：使用 entryId、body 和 status 调用 create_comment
2. 回复该评论：使用 entryId、body、status 和 parent（要回复的评论 ID）调用 create_comment
3. 继续线程：将线程中任意评论的 ID 用作 parent 来回复该评论

批量操作

• bulk_publish：在单次操作中发布多个条目和资源。接受实体（条目和资源）数组，并批量处理发布。
• bulk_unpublish：在单次操作中取消发布多个条目和资源。与 bulk_publish 类似，但会从交付 API 中移除内容。
• bulk_validate：检查多个条目的内容一致性、引用和必填字段。返回验证结果，但不会修改内容。

资源管理

• list_assets：分页列出资源（每页 3 个条目）
• upload_asset：上传带有元数据的新资源
• get_asset：获取资源详情和信息
• update_asset：更新资源元数据和文件
• delete_asset：从空间中移除资源
• publish_asset：将资源发布到交付 API
• unpublish_asset：从交付 API 中取消发布资源

空间和环境管理

• list_spaces：列出可用空间
• get_space：获取空间详情
• list_environments：列出空间中的环境
• create_environment：创建新环境
• delete_environment：移除环境

内容类型管理

• list_content_types：列出可用内容类型
• get_content_type：获取内容类型详情
• create_content_type：创建新内容类型
• update_content_type：更新内容类型
• delete_content_type：移除内容类型
• publish_content_type：发布内容类型

开发工具

MCP Inspector

项目包含 MCP Inspector 工具，可帮助开发和调试：

• 检查模式：运行 npm run inspect 启动检查器，然后访问 http://localhost:5173 打开检查器
• 监视模式：使用 npm run inspect:watch，在文件发生更改时自动重启检查器
• 可视化界面：检查器提供 Web 界面，可用于测试和调试 MCP 工具
• 实时测试：试用工具并立即查看其响应
• 批量操作测试：测试和监控批量操作，并通过可视化反馈查看进度和结果

项目还包含 npm run dev 命令，每次发生更改时都会重新构建并重新加载 MCP 服务。

配置

先决条件

1. 在 Contentful 创建 Contentful 账户
2. 在账户设置中生成 Content Management API 令牌

环境变量

这些变量也可以作为参数设置

• CONTENTFUL_HOST / --host：Contentful Management API 端点（默认为 https://api.contentful.com）
• CONTENTFUL_MANAGEMENT_ACCESS_TOKEN / --management-token：你的 Content Management API 令牌
• ENABLE_HTTP_SERVER / --http：设为 "true" 以启用 HTTP/SSE 模式
• HTTP_PORT / --port：HTTP 服务的端口（默认值：3000）
• HTTP_HOST / --http-host：HTTP 服务的主机（默认值：localhost）
• DISABLE_AI_ACTIONS：设为 "true" 以禁用启动时获取 AI Actions（如果你无法使用此功能，此设置会很有用）

空间和环境范围限定

你可以限定 spaceId 和 EnvironmentId，确保 LLM 只对指定的空间／环境 ID 执行操作。 这主要用于支持在特定空间内运行的 Agent。如果同时设置了 SPACE_ID 和 ENVIRONMENT_ID 环境变量， 工具就不会提示需要这些值，处理程序也会使用环境变量执行 CMA 操作。 你也将无法访问 space-handler 中的工具，因为这些工具面向多个空间。 你也可以通过参数 --space-id 和 --environment-id 添加 SPACE_ID 和 ENVIRONMENT_ID

使用 App Identity

除了提供 Management token，你还可以使用 App Identity 处理身份验证。你需要设置并安装一个 Contentful App，并在调用 MCP 服务时设置以下参数：

• --app-id = 提供 Apptoken 的 app Id
• --private-key = 你在用户界面中为 app 创建的私钥，与 app_id 关联
• --space-id = 安装该 app 的 spaceId
• --environment-id = 安装该 app 的 environmentId（位于该 space 中）。

使用这些值，MCP 服务将请求一个临时 AppToken，以便在指定的空间／environment-id 中执行内容操作。这在将此 MCP 服务用于充当 MCP 客户端的后端系统（例如聊天 Agent）时尤其有用。

在 Claude Desktop 中使用

你无需克隆此仓库即可使用此 MCP，只需将其添加到 你的 claude_desktop_config.json 中：

添加或编辑 ~/Library/Application Support/Claude/claude_desktop_config.json 并添加以下几行：

{
  "mcpServers": {
    "contentful": {
      "command": "npx",
      "args": ["-y", "@ivotoby/contentful-management-mcp-server"],
      "env": {
        "CONTENTFUL_MANAGEMENT_ACCESS_TOKEN": "<Your CMA token>"
      }
    }
  }
}

如果你的 MCPClient 不支持设置环境变量，也可以像这样通过参数设置 management token：

{
  "mcpServers": {
    "contentful": {
      "command": "npx",
      "args": [
        "-y",
        "@ivotoby/contentful-management-mcp-server",
        "--management-token",
        "<your token>",
        "--host",
        "http://api.contentful.com"
      ]
    }
  }
}

通过 Smithery 安装

通过 Smithery 自动为 Claude Desktop 安装 Contentful Management Server：

npx -y @smithery/cli install @ivotoby/contentful-management-mcp-server --client claude

开发和使用 Claude desktop

如果你想参与贡献并测试 Claude 如何处理你的贡献；

• 运行 npm run dev，这将启动监视程序，在每次更改时重新构建 MCP 服务
• 更新 claude_desktop_config.json，使其直接引用该项目，即；

{
  "mcpServers": {
    "contentful": {
      "command": "node",
      "args": ["/Users/ivo/workspace/contentful-mcp/bin/mcp-server.js"],
      "env": {
        "CONTENTFUL_MANAGEMENT_ACCESS_TOKEN": "<Your CMA Token>"
      }
    }
  }
}

这样你就可以直接使用 Claude 测试 MCP 服务中的任何修改；不过，如果你添加了新的工具／资源，则需要重启 Claude Desktop

传输模式

MCP 服务支持两种传输模式：

stdio 传输

默认传输模式使用标准输入／输出流进行通信。这非常适合与支持 stdio 传输的 MCP 客户端集成，例如 Claude Desktop。

要使用 stdio 模式，只需在不带 --http 标志的情况下运行服务：

npx -y contentful-mcp --management-token YOUR_TOKEN
# or alternatively
npx -y @ivotoby/contentful-management-mcp-server --management-token YOUR_TOKEN

StreamableHTTP 传输

服务还支持 MCP 协议中定义的 StreamableHTTP 传输模式。此模式适用于基于 Web 的集成，或将服务作为独立服务运行的场景。

要使用 StreamableHTTP 模式，请使用 --http 标志运行：

npx -y contentful-mcp --management-token YOUR_TOKEN --http --port 3000
# or alternatively
npx -y @ivotoby/contentful-management-mcp-server --management-token YOUR_TOKEN --http --port 3000

StreamableHTTP 详情

• 使用官方 MCP StreamableHTTP 传输
• 支持标准 MCP 协议操作
• 包含用于维持状态的会话管理
• 正确处理 initialize/notify 模式
• 兼容标准 MCP 客户端
• 以现代方式取代已弃用的 SSE 传输

该实现遵循标准 MCP 协议规范，因此任何 MCP 客户端都无需特殊处理即可连接到服务。

错误处理

该服务针对以下情况实现了全面的错误处理：

• 身份验证失败
• 速率限制
• 无效请求
• 网络问题
• API 特定错误

许可证

MIT 许可证

重要提示

此 MCP 服务允许 Claude（或其他能够使用 MCP 资源的 Agent）更新和删除内容、空间及内容模型。因此，请务必谨慎设置允许 Claude 对你的 Contentful 空间执行的操作！

此 MCP 服务目前尚未获得 Contentful 官方支持