Strapi MCP 服务深度实战与 Cursor 集成白皮书

Strapi MCP 是 Strapi 5 社区版内置的 Model Context Protocol (MCP) 服务器，允许 AI 助手（如 Claude、Cursor）通过自然语言直接管理 Strapi CMS 内容。无需额外部署 MCP 服务器，只需一个 Admin Token 即可让 AI 客户端与 Strapi 进行结构化内容交互，支持完整的 CRUD、发布/取消发布、国际化等操作。

适用场景与技术亮点

Strapi MCP 最适合需要让 AI 助手直接通过自然语言管理 Strapi CMS 内容的团队。典型场景包括：

1. 内容编辑团队：使用 AI 快速创建、更新、发布博客文章或页面，无需手动操作管理面板
2. 开发者测试环境：通过 AI 助手在开发环境中批量操作内容（如创建测试数据、清理旧内容）
3. AI 后端内容库：将 Strapi 作为 AI 应用的后端内容库，让 AI 代理直接读写内容

技术亮点：

• 零额外部署：Strapi 5 内置 MCP 端点，无需安装第三方 MCP 服务器
• 权限复用：直接使用 Admin Token，权限粒度与 Strapi 管理面板一致
• Draft & Publish 原生支持：自动为每个内容类型生成发布/取消发布/丢弃草稿工具
• 国际化原生支持：可指定语言参数创建多语言内容
• Streamable HTTP 传输：配置简单，仅需 URL + Token，无需复杂网络配置

适合的大模型：任何支持 MCP 协议的 AI 客户端（Claude Desktop、Claude Code、Cursor、Windsurf 等），尤其适合需要结构化内容管理能力的场景。

架构优势与同类方案对比

核心优势：Strapi MCP 的零额外部署、权限与 Strapi 管理面板一致、支持 Draft & Publish 工作流，使其成为 CMS + AI 集成场景中最简洁高效的方案。

安装与核心启动命令

前提条件

• Strapi 5 项目已启动（开发模式或生产模式）
• 已生成有效的 Admin Token（在 Strapi 管理面板：Settings → API Tokens → Create new API Token）

启动 Strapi 开发模式

bash
# 进入 Strapi 项目目录
cd your-strapi-project

# 启动开发模式（默认端口 1337）
npm run develop

连接 AI 客户端到 Strapi MCP

bash
# 使用 npx 直接运行 mcp-remote 客户端
npx -y mcp-remote http://localhost:1337/mcp --header "Authorization: Bearer YOUR_ADMIN_TOKEN"

注意：YOUR_ADMIN_TOKEN 必须替换为实际生成的 Admin Token。生产环境建议使用环境变量注入 Token。

启动参数对照表格

配置示例（Strapi 配置文件 config/middlewares.js）

javascript
module.exports = [
  'strapi::logger',
  'strapi::errors',
  'strapi::security',
  'strapi::cors',
  'strapi::poweredBy',
  'strapi::query',
  'strapi::body',
  'strapi::session',
  'strapi::favicon',
  'strapi::public',
  {
    name: 'strapi::mcp',
    config: {
      enabled: true,
      connectTimeoutMs: 5000,
      requestTimeoutMs: 120000, // 生产环境建议增大超时时间
    },
  },
];

Claude Desktop 与 Cursor 集成配置

Claude Desktop 配置

在 Claude Desktop 的配置文件（claude_desktop_config.json）中添加以下内容：

json
{
  "mcpServers": {
    "strapi-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:1337/mcp",
        "--header",
        "Authorization: Bearer YOUR_ADMIN_TOKEN"
      ]
    }
  }
}

配置步骤：

1. 打开 Claude Desktop
2. 进入设置 → Developer → Edit Config
3. 将上述 JSON 粘贴到 claude_desktop_config.json 中
4. 保存文件并重启 Claude Desktop
5. 在对话中测试：列出 Strapi 中的所有内容类型

Cursor 配置

在 Cursor 的 MCP 配置文件中添加：

json
{
  "mcpServers": {
    "strapi-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:1337/mcp",
        "--header",
        "Authorization: Bearer YOUR_ADMIN_TOKEN"
      ]
    }
  }
}

配置步骤：

1. 打开 Cursor
2. 进入设置 → Features → MCP Servers
3. 点击 "Add new MCP Server"
4. 选择 "Command" 类型
5. 在 "Command" 字段输入：npx -y mcp-remote http://localhost:1337/mcp --header "Authorization: Bearer YOUR_ADMIN_TOKEN"
6. 保存配置
7. 在 Cursor 的 AI 对话中测试：创建一篇新的博客文章，标题为 "Hello World"

生产环境部署建议与安全限制

性能与并发

• 超时配置：生产环境建议将 requestTimeoutMs 设置为 120000ms（2分钟），以应对复杂查询或高负载场景
• 负载均衡：多个 AI 客户端同时操作时，建议使用负载均衡分发请求到多个 Strapi 实例
• 数据库优化：确保 Strapi 使用的数据库（PostgreSQL/MySQL）有足够的连接池和查询优化

安全性

• Token 管理：Admin Token 必须妥善保管，切勿硬编码在客户端配置文件中。建议使用环境变量或密钥管理服务（如 Vault）注入 Token
• HTTPS 加密：生产环境必须强制使用 HTTPS 加密传输，避免 Token 在网络上明文传输
• 最小权限原则：为不同 AI 客户端创建不同权限的 Token，仅授予所需内容类型的必要操作权限
• 防火墙规则：MCP 端点 /mcp 需要对外暴露时，配置防火墙规则仅允许可信 IP 访问

并发冲突处理

• 乐观锁机制：Strapi 使用乐观锁处理并发写入，当多个客户端同时更新同一文档时，后到的更新会返回 409 Conflict 错误
• 重试逻辑：AI 客户端应实现指数退避重试逻辑，处理并发冲突
• 串行操作：对于批量操作，建议串行执行以避免冲突

日志与监控

• 启用日志：生产环境启用 Strapi 的日志记录（通过 Pino），监控 MCP 请求的耗时和错误率
• 监控指标：关注 MCP 请求的响应时间、错误率、并发连接数
• 告警设置：设置告警规则，当错误率超过阈值时通知运维团队

磁盘与网络优化

• 磁盘 I/O：Strapi 的媒体文件上传会消耗磁盘 I/O，建议使用对象存储（如 S3）分离媒体文件
• 网络延迟：AI 客户端与 Strapi 服务器之间的网络延迟会影响 MCP 响应时间，建议部署在同一区域

常见报错与故障排除

错误 1：连接被拒绝

Error: connect ECONNREFUSED ::1:1337

排查步骤：

1. 检查 Strapi 是否已启动：ps aux | grep strapi
2. 确认端口配置：lsof -i :1337
3. 如果 Strapi 运行在远程服务器，检查防火墙规则：curl http://your-server:1337/mcp
4. 在客户端配置中使用正确的 IP/域名

错误 2：未授权（401）

Error: Unauthorized (401) - Invalid or missing Authorization header

排查步骤：

1. 检查 Token 是否已复制完整（包括 Bearer 前缀）
2. 在 Strapi 管理面板验证 Token 是否有效：Settings → API Tokens
3. 确认 Token 未过期或被撤销
4. 测试 Token 有效性：curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:1337/mcp

错误 3：请求超时

Error: Timeout - Request timed out after 60000ms

排查步骤：

1. 检查 Strapi 服务器负载：top 或 htop
2. 增加 requestTimeoutMs 配置值：120000ms
3. 优化数据库查询性能：添加索引、优化查询
4. 减少单次请求的数据量（如分页查询）

错误 4：并发冲突（409）

Error: 409 Conflict - Version mismatch

排查步骤：

1. 确认是否有多个客户端同时操作同一文档
2. 在 AI 客户端中实现重试逻辑（指数退避）
3. 确保同一时间只有一个客户端操作关键文档
4. 对于批量操作，使用串行执行

常见问题解答 (FAQ)

Q: Strapi MCP 是否支持生产环境？如何确保安全性？

A: 是的，Strapi MCP 支持生产环境。安全性建议：

1. 使用 HTTPS 加密所有通信，避免 Token 明文传输
2. 创建专用 Admin Token，并赋予最小必要权限（如只读 Token 用于查询，读写分离）
3. 将 Token 存储在环境变量或密钥管理服务中，不要硬编码在客户端配置
4. 配置防火墙规则，仅允许可信 IP 访问 /mcp 端点
5. 定期轮换 Token
6. 启用 Strapi 的访问日志，监控异常请求

Q: 如何让 AI 客户端只读 Strapi 内容，而不能修改或删除？

A: 在 Strapi 管理面板中创建一个新的 Admin Token，并在设置权限时，只为该 Token 授予所需内容类型的 'Read' 权限（不勾选 Create、Update、Delete、Publish 等）。这样，AI 客户端连接后只会看到 list 和 get 工具，无法执行写入操作。这是实现只读访问的最佳实践。

Q: Strapi MCP 支持哪些内容类型？如何处理自定义字段（如关系、组件、动态区域）？

A: Strapi MCP 支持所有内容类型（Collection Type 和 Single Type），包括启用了 Draft & Publish 和 i18n 的类型。对于自定义字段（如关系、组件、动态区域），MCP 工具会暴露对应的参数。例如，创建文章时可以指定分类（关系字段）或填充组件数据。但需要注意的是，AI 客户端可能无法完全理解复杂的数据结构（如嵌套组件），建议在提示词中明确说明字段结构，或先通过 list/get 工具获取现有数据的结构作为参考。

Q: 如何调试 Strapi MCP 连接问题？

A: 使用以下命令进行调试：

bash
# 测试 MCP 端点是否可达
curl -v http://localhost:1337/mcp

# 测试 Token 有效性
curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:1337/mcp

# 查看 Strapi 日志
npm run strapi logs

# 使用 mcp-remote 的调试模式
npx -y mcp-remote http://localhost:1337/mcp --header "Authorization: Bearer YOUR_TOKEN" --debug

相关深度解决方案

• 在配置当前服务时，如果您需要实现更复杂的架构或多源数据整合，建议配合参考我们整理的 Strapi MCP 服务深度实战与 Cursor 集成白皮书。
• 在配置当前服务时，如果您需要实现更复杂的架构或多源数据整合，建议配合参考我们整理的 Salesforce MCP 服务深度实战与 Cursor 集成白皮书。