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 的独特卖点：

• 唯一提供官方内置 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：

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

启动参数对照表格

配置示例（在 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：

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

Cursor：

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

Windsurf：

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

配置验证

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

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

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

安全限制

1. Admin Token 最小权限原则

   • 避免使用超级管理员 Token
   • 仅授予必要的内容类型和操作权限
   • 定期轮换 Token（建议每月一次）

2. 网络层防护

   • 通过反向代理（Nginx）限制 /mcp 端点的 IP 白名单
   • 强制 HTTPS 加密传输
   • 配置 WAF 规则防止滥用

3. 端点保护配置示例（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;
}

并发与性能优化

1. 数据库选择：生产环境必须使用 PostgreSQL，避免 SQLite 的并发写入锁问题
2. 连接池配置：在 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,
      },
    },
  },
});

3. 超时参数调整：根据内容量调整 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

排查步骤：

1. 检查 Strapi 服务器是否运行：curl http://localhost:1337/mcp
2. 确认防火墙未阻止端口 1337
3. 增加 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

排查步骤：

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

解决方案：

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

错误 3：Tool not found

错误信息：

Error: Tool 'publish-entry' not found

排查步骤：

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

解决方案：

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

错误 4：Request timeout

错误信息：

Error: Request timeout after 60000ms

排查步骤：

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

解决方案：

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