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

Strapi MCP (Model Context Protocol) 是 Strapi CMS 官方内置的 AI 集成层，允许 Claude、Cursor 等 AI 助手通过自然语言直接管理 Strapi 内容。本白皮书将深入解析其架构优势、实战配置与生产部署要点，帮助开发者快速构建 AI 驱动的内容管理系统。

适用场景与技术亮点

Strapi MCP 最适合需要让 AI 助手通过自然语言管理 Strapi CMS 内容的场景，核心解决以下痛点：

内容运营效率提升：运营团队可使用 AI 快速创建、编辑、发布博客文章或产品页面，无需学习 Strapi 管理面板操作
开发测试数据生成：开发者通过 AI 助手在开发环境中快速生成测试数据，加速原型验证
自动化内容工作流：将 Strapi 作为 AI 应用的内容后端，实现从内容生成到发布的自动化流水线

最适配的大模型与 Host：

Claude Desktop / Claude Code：原生 MCP 支持，配置最简便
Cursor：通过 mcp-remote 桥接，支持自然语言内容管理
Windsurf：同样支持 MCP 协议，配置方式与 Cursor 类似

技术亮点：

官方内置支持，无需安装第三方 MCP 适配器
自动为所有内容类型生成 CRUD 工具，包括 Draft & Publish 全生命周期管理
原生支持 i18n 国际化参数
使用 Streamable HTTP 传输协议，支持标准 HTTP 头认证

架构优势与同类方案对比

对比维度	Strapi MCP	WordPress MCP (第三方)	自定义 CMS MCP
集成方式	官方内置，零额外安装	需要安装第三方 MCP 适配器插件	需自行开发 MCP 服务器
权限控制	复用 Admin Token，粒度细（读/写/发布/删除）	通常只有全局 API Key	取决于实现，通常较粗糙
传输协议	Streamable HTTP，支持标准 HTTP 头认证	多为 stdio 传输，不适合远程部署	取决于实现
国际化支持	原生支持 i18n 参数	通常需手动处理多语言	需自行实现
内容生命周期	支持 Draft & Publish 全流程	取决于插件实现	需自行实现
维护成本	官方持续更新，兼容性有保障	依赖第三方维护，可能滞后	高，需自行维护

Strapi MCP 的独特卖点：

唯一提供官方内置 MCP 支持的 CMS
配置极简：仅需 Admin Token 即可启用
自动适配所有内容类型和字段类型
支持 Draft & Publish 全生命周期管理

安装与核心启动命令

Strapi MCP 是 Strapi 5 的内置功能，无需额外安装。启动 MCP 客户端只需一条命令：

bash
npx -y mcp-remote http://localhost:1337/mcp --header "Authorization: Bearer YOUR_ADMIN_TOKEN"

参数说明：

http://localhost:1337/mcp：Strapi MCP 端点地址，默认端口 1337
YOUR_ADMIN_TOKEN：在 Strapi 管理面板生成的 Admin Token

获取 Admin Token：

登录 Strapi 管理面板（默认 http://localhost:1337/admin）
进入 Settings → Global Settings → API Tokens
点击 "Create new API Token"，选择 "Custom" 类型
授予所需权限（建议最小权限原则）
复制生成的 Token 值

启动参数对照表格

参数名	是否必填	默认值	作用解释
`enabled`	否	`false`	启用或禁用 MCP 服务器。需在 Strapi 配置文件中设置为 `true` 才能激活 MCP 端点
`connectTimeoutMs`	否	`5000`	MCP 传输连接超时时间（毫秒）。超过此时间未建立连接则请求中止
`requestTimeoutMs`	否	`60000`	单个 MCP 请求完成的最大等待时间（毫秒）。超时则请求失败

配置示例（在 config/plugins.js 或 config/middlewares.js 中）：

javascript
module.exports = {
  'strapi-mcp': {
    enabled: true,
    config: {
      connectTimeoutMs: 10000,  // 远程连接时建议增大
      requestTimeoutMs: 120000, // 批量操作时建议增大
    },
  },
};

Claude Desktop 与 Cursor 集成配置

标准 MCP 配置 JSON

以下 JSON 配置适用于 Claude Desktop 和 Cursor：

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

配置写入步骤

Claude Desktop：

打开 Claude Desktop 设置
导航到 Developer → Edit Config
在 claude_desktop_config.json 中添加上述 JSON
重启 Claude Desktop

Cursor：

打开 Cursor 设置（Cmd + Shift + P → Preferences: Open Settings (JSON)）
在 settings.json 中添加 mcpServers 配置
保存文件，Cursor 自动加载 MCP 服务器

Windsurf：

打开 Windsurf 设置
在 MCP 配置部分添加相同 JSON
重启 Windsurf

配置验证

启动后，AI 客户端会自动发现 Strapi MCP 提供的工具。在 Claude Desktop 中，你会看到工具列表包含：

list-content-types：列出所有内容类型
create-entry：创建内容条目
update-entry：更新内容条目
delete-entry：删除内容条目
publish-entry：发布草稿
unpublish-entry：取消发布
find-entries：查询内容条目

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

安全限制

Admin Token 最小权限原则
- 避免使用超级管理员 Token
- 仅授予必要的内容类型和操作权限
- 定期轮换 Token（建议每月一次）
网络层防护
- 通过反向代理（Nginx）限制 /mcp 端点的 IP 白名单
- 强制 HTTPS 加密传输
- 配置 WAF 规则防止滥用
端点保护配置示例（Nginx）

nginx
location /mcp {
    # 仅允许内网 IP 访问
    allow 10.0.0.0/8;
    allow 192.168.0.0/16;
    deny all;
    
    # 强制 HTTPS
    if ($scheme != "https") {
        return 301 https://$host$request_uri;
    }
    
    proxy_pass http://localhost:1337;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}

并发与性能优化

数据库选择：生产环境必须使用 PostgreSQL，避免 SQLite 的并发写入锁问题
连接池配置：在 Strapi 配置中优化数据库连接池

javascript
// config/database.js
module.exports = ({ env }) => ({
  connection: {
    client: 'postgres',
    connection: {
      host: env('DATABASE_HOST', 'localhost'),
      port: env.int('DATABASE_PORT', 5432),
      database: env('DATABASE_NAME', 'strapi'),
      user: env('DATABASE_USER', 'strapi'),
      password: env('DATABASE_PASSWORD', 'password'),
      pool: {
        min: 2,
        max: 10,
        acquireTimeoutMillis: 30000,
      },
    },
  },
});

超时参数调整：根据内容量调整 requestTimeoutMs

javascript
// config/plugins.js
module.exports = {
  'strapi-mcp': {
    enabled: true,
    config: {
      connectTimeoutMs: 10000,  // 远程连接
      requestTimeoutMs: 120000, // 批量操作
    },
  },
};

日志与监控

生产环境禁用开发模式的 log 工具（设置 autoReload: false）
配置集中式日志收集（如 ELK Stack）
监控 MCP 请求频率和错误率

常见报错与故障排除

错误 1：Connection timeout

错误信息：

Error: Connection timeout after 5000ms

排查步骤：

检查 Strapi 服务器是否运行：curl http://localhost:1337/mcp
确认防火墙未阻止端口 1337
增加 connectTimeoutMs 到 10000

解决方案：

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

错误 2：Authorization failed (401)

错误信息：

Error: 401 Unauthorized - Invalid token

排查步骤：

在 Strapi 管理面板重新生成 Admin Token
确认 Token 未过期
检查 Token 权限是否包含所需操作

解决方案：

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

错误 3：Tool not found

错误信息：

Error: Tool 'publish-entry' not found

排查步骤：

检查 Admin Token 是否包含 publish 权限
确认内容类型已启用 Draft & Publish
在 Strapi 管理面板检查内容类型配置

解决方案：

在 Strapi 管理面板中，为 Token 关联的角色授予对应内容类型的发布权限
确保内容类型的 "Draft & Publish" 选项已启用

错误 4：Request timeout

错误信息：

Error: Request timeout after 60000ms

排查步骤：

检查操作的数据量是否过大
查看 Strapi 服务器日志是否有性能瓶颈
考虑分批次操作

解决方案：

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

常见问题解答 (FAQ)

Q: Strapi MCP 支持哪些内容类型的操作？是否支持自定义字段？

A: Strapi MCP 自动为所有内容类型（Collection Type 和 Single Type）生成 CRUD 工具，包括 Draft & Publish 操作。支持所有 Strapi 内置字段类型（如文本、富文本、关系、媒体等），但媒体上传操作未通过 MCP 暴露，需要单独处理。自定义字段（如 JSON、UID）也受支持，但 AI 客户端可能无法正确推断其格式，建议在提示词中明确说明。

Q: 如何确保 MCP 操作的安全性？特别是生产环境。

A: 生产环境安全建议：1) 使用最小权限的 Admin Token，仅授予必要的内容类型和操作权限；2) 通过反向代理（如 Nginx）限制 /mcp 端点的访问 IP；3) 强制 HTTPS 加密传输；4) 设置合理的超时参数（connectTimeoutMs 和 requestTimeoutMs）；5) 禁用开发模式下的 log 工具（autoReload: false）；6) 定期轮换 Admin Token；7) 监控 Strapi 日志以检测异常 MCP 请求。

Q: Strapi MCP 与直接使用 Strapi REST API 相比有什么优势？

A: 主要优势：1) 自然语言交互：AI 客户端可以直接理解用户意图（如“创建一篇标题为 X 的文章”）并自动调用对应工具，无需手动构造 API 请求；2) 工具发现：MCP 客户端自动获取可用工具及其参数 schema，减少文档查阅；3) 上下文感知：AI 可以结合对话历史进行多步操作（如先查询再更新）；4) 统一认证：复用 Strapi Admin Token，无需额外 API Key。劣势：MCP 目前不支持批量操作和复杂查询（如聚合），对于高级用例仍需使用 REST API。

Q: Strapi MCP 是否支持远程部署？如何配置？

A: 支持远程部署。只需将 http://localhost:1337/mcp 替换为远程服务器的实际地址（如 https://your-strapi-domain.com/mcp）。注意：远程部署时必须使用 HTTPS 加密传输，并确保反向代理正确转发 /mcp 端点。同时建议增大 connectTimeoutMs 以应对网络延迟。

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

适用场景与技术亮点

架构优势与同类方案对比

安装与核心启动命令

启动参数对照表格

Claude Desktop 与 Cursor 集成配置

标准 MCP 配置 JSON

配置写入步骤

配置验证

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

安全限制

并发与性能优化

日志与监控

常见报错与故障排除

错误 1：Connection timeout

错误 2：Authorization failed (401)

错误 3：Tool not found

错误 4：Request timeout

常见问题解答 (FAQ)

Q: Strapi MCP 支持哪些内容类型的操作？是否支持自定义字段？

Q: 如何确保 MCP 操作的安全性？特别是生产环境。

Q: Strapi MCP 与直接使用 Strapi REST API 相比有什么优势？

Q: Strapi MCP 是否支持远程部署？如何配置？

相关深度解决方案