Misterboe Strapi MCP Server

🚀 Strapi MCP 服务器

Strapi MCP（模型上下文协议）服务器为 AI 助手提供了标准化接口，使其能够与 Strapi 实例进行交互，支持内容类型和 REST API 操作，助力开发者高效开展内容管理和媒体处理工作。

🚀 快速开始

安装指南

在 Claude Desktop 配置中，可直接使用 npx 运行以下命令来安装服务器：

npx strapi-mcp-server

创建配置文件

创建或编辑配置文件 ~/.mcp/strapi-mcp-server.config.json，并添加以下内容：

{
  "apiUrl": "http://localhost:1337", // Strapi 实例的 URL，默认为 http://localhost:1337
  "version": "v5",                 // 支持的 Strapi 版本，可选值：v4, v5
  "jwtToken": "your_jwt_token"     // Strapi 的 JWT 认证令牌
}

✨ 主要特性

核心功能

1. 内容查询：
   • 可获取单个或多个内容条目。
   • 支持过滤、排序和分页功能。
2. 媒体上传：
   • 支持上传图片或其他文件。
   • 能自动进行格式转换和优化（如转换为 WebP 格式）。
   • 支持自定义元数据。
3. 版本支持：
   • 支持 Strapi v4 和 v5 不同的 API 结构和数据格式。

💻 使用示例

基础用法

查询内容

// 获取单个文章
strapi_get_content({
  server: "default",
  endpoint: "articles",
  id: "123"
});

// 获取多篇文章并分页
strapi_get_content({
  server: "default",
  endpoint: "articles",
  params: {
    pagination: { page: 1, pageSize: 25 },
    sort: ["createdAt:desc"]
  }
});

媒体上传

// 上传并优化图片
strapi_upload_media({
  server: "default",
  url: "https://example.com/image.jpg",
  format: "webp",
  quality: 80,
  metadata: {
    name: "My Image",
    caption: "Image Caption",
    alternativeText: "Alt Text"
  }
});

📚 详细文档

版本差异（v4 vs v5）

v4

• 使用数字 ID。
• 属性结构嵌套。
• 响应数据包含在 data 包裹器中。
• 采用传统的 REST 模式。
• 需要外部 i18n 插件。

v5

• 使用文档 ID。
• 数据结构扁平化。
• 可直接访问属性。
• 强化了 JWT 安全机制。
• 集成了 i18n 支持。
• 具备新的文档服务 API。

安全特性

写保护策略

服务器实施严格的写入保护：

• 所有写入操作（POST、PUT、DELETE）均需明确授权。
• 受保护的操作包括：
  • 创建（POST）
  • 更新（PUT）
  • 删除（DELETE）
  • 媒体上传
• 每次操作均会记录日志并进行验证。

最佳实践

1. 检查内容类型：使用 strapi_get_content_types 确认字段和结构。
2. 正确使用 URL 格式：区分复数和单数形式的端点。
3. 包含错误处理机制：在每次请求中添加异常捕获。
4. 设置适当权限：根据角色和权限控制 API 访问。

故障排除

常见问题

1. 401 未认证错误：
   • 检查 JWT 令牌是否正确配置。
   • 确保令牌在 Strapi 实例中启用。
2. 404 资源未找到：
   • 核对端点名称和 ID 是否正确。
   • 确认 Strapi 实例的 API 端点已正确设置。
3. 数据格式错误：
   • 检查请求参数是否与目标版本（v4 或 v5）匹配。
   • 确保传递的数据结构符合要求。

贡献指南

欢迎社区贡献！请通过提交 Pull Request 的方式改进项目。

• 提交问题：GitHub Issues
• 提交功能或修复：Pull Request