Contentful MCP服务器

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

• 请注意*：如果您不关心代码，只是想在Claude Desktop（或其他支持MCP服务器的工具）中使用此MCP，您不需要克隆此仓库，只需在Claude Desktop中设置即可，参考"与Claude Desktop一起使用"部分了解安装说明。

功能特点

• 内容管理：对条目和资产提供完整的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创建账户
2. 从账户设置生成内容管理API令牌

环境变量

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

• CONTENTFUL_HOST / --host：Contentful管理API端点（默认为https://api.contentful.com）
• CONTENTFUL_MANAGEMENT_ACCESS_TOKEN / --management-token：您的内容管理API令牌
• ENABLE_HTTP_SERVER / --http：设置为"true"以启用HTTP/SSE模式
• HTTP_PORT / --port：HTTP服务器端口（默认：3000）
• HTTP_HOST / --http-host：HTTP服务器主机（默认：localhost）

空间和环境范围限定

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

使用应用身份

除了提供管理令牌外，您还可以利用应用身份
进行身份验证。您需要设置和安装Contentful应用，并在调用MCP服务器时设置以下参数：

• --app-id = 提供Apptoken的应用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管理服务器：

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

开发和使用Claude桌面

如果您想贡献代码并测试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

传输模式

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

stdio传输

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

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

npx -y contentful-mcp --management-token YOUR_TOKEN
# 或者
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
# 或者
npx -y @ivotoby/contentful-management-mcp-server --management-token YOUR_TOKEN --http --port 3000

StreamableHTTP详情

• 使用官方MCP StreamableHTTP传输
• 支持标准MCP协议操作
• 包含会话管理以保持状态
• 正确处理初始化/通知模式
• 与标准MCP客户端兼容
• 用现代方法替代已弃用的SSE传输

该实现遵循标准MCP协议规范，允许任何MCP客户端连接到服务器而无需特殊处理。

错误处理

服务器实现了全面的错误处理，包括：

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

许可证

MIT许可证

注意事项

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

此MCP服务器尚未得到Contentful的官方支持