Contentful MCP 服务器

一个与 Contentful 的内容管理 API 集成的 MCP服务器实现，提供全面的内容管理功能。

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

<a href="https://glama.ai/mcp/servers/l2fxeaot4p"><img width="380" height="200" src="https://glama.ai/mcp/servers/l2fxeaot4p/badge" alt="contentful-mcp MCP server" /></a>

功能

• 内容管理: 针对条目和资产的完整 CRUD 操作
• 空间管理: 创建、更新和管理空间和环境
• 内容类型: 管理内容类型定义
• 本地化: 支持多种语言环境
• 发布: 控制内容发布工作流程
• 批量操作: 跨多个条目和资产执行批量发布、取消发布和验证
• 智能分页: 列表操作每次请求最多返回 3 个项目，以防止上下文窗口溢出，并具有内置分页支持

分页

为了防止 LLM 中的上下文窗口溢出，列表操作（如 search_entries 和 list_assets）限制为每次请求 3 个项目。每个响应包括：

• 可用项目总数
• 当前项目页面（最多 3 个）
• 剩余项目数
• 下一页的跳过值
• 提示 LLM 提供检索更多项目的消息

此分页系统允许 LLM 有效地处理大型数据集，同时保持上下文窗口限制。

批量操作

批量操作功能提供同时管理多个内容项的有效方式：

• 异步处理: 操作异步运行并提供状态更新
• 高效的内容管理: 在单个 API 调用中处理多个条目或资产
• 状态跟踪: 使用成功和失败计数来监控进度
• 资源优化: 减少 API 调用并提高批量操作的性能

这些批量操作工具非常适合内容迁移、批量更新或批量发布工作流程。

工具

条目管理

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

批量操作

• 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 检查器

该项目包含一个 MCP 检查器工具，可帮助进行开发和调试：

• 检查模式: 运行 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 令牌

空间和环境范围限定 (实验性)

您可以限定 spaceId 和 EnvironmentId，以确保 LLM 仅对定义的 space/env ID 执行操作。 这主要是为了支持在特定空间内运行的代理。如果同时设置了 SPACE_ID 和 ENVIRONMENT_ID 环境变量， 这些工具将不会报告需要这些值，并且处理程序将使用环境变量来执行 CMA 操作。 您还将失去对空间处理程序中工具的访问权限，因为这些工具跨越多个空间。 您还可以使用参数 --space-id 和 --environment-id 添加 SPACE_ID 和 ENVIRONMENT_ID

使用 App Identity

除了提供管理令牌之外，您还可以利用 App Identity 来处理身份验证。您必须设置并安装 Contentful App，并在调用 MCP 服务器时设置以下参数：

• --app-id = 提供 Apptoken 的 app Id
• --private-key = 您在用户界面中使用您的应用程序创建的私钥，与 app_id 相关联
• --space-id = 安装应用程序的空间 ID
• --environment-id = 安装应用程序的环境 ID（在空间内）。

使用这些值，MCP 服务器将请求一个临时 AppToken 以在定义的空间/环境 ID 中执行内容操作。当在充当 MCP 客户端的后端系统（如聊天代理）中使用此 MCP 服务器时，这尤其有用。

与 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": "<您的 CMA 令牌>"
      }
    }
  }
}

如果您的 MCPClient 不支持设置环境变量，您也可以使用如下参数设置管理令牌：

{
  "mcpServers": {
    "contentful": {
      "command": "npx",
      "args": ["-y", "@ivotoby/contentful-management-mcp-server",'--management-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": "<您的 CMA 令牌>"
      }
    }
  }
}

这将允许您直接使用 Claude 测试 MCP 服务器中的任何修改，但是；如果您添加新的工具/资源，则需要重新启动 Claude Desktop

错误处理

服务器实现了全面的错误处理，用于：

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

许可证

MIT 许可证

细则

此 MCP 服务器使 Claude（或其他可以消耗 MCP 资源的代理）能够更新、删除内容、空间和内容模型。因此，请确保您允许 Claude 对您的 Contentful 空间执行哪些操作！