Strapi MCP 服务器

一个用于与 Strapi CMS 交互的模型上下文协议服务器。该服务器通过标准化接口使 AI 助手能够与您的 Strapi 实例进行交互，支持内容类型和 REST API 操作。

⚠️ 重要免责声明：此软件是在 AI 技术的辅助下开发的。它按原样提供，在未经彻底测试和验证之前不应在生产环境中使用。代码可能包含错误、安全漏洞或意外行为。仅用于研究、学习或开发目的，风险自负。

更新日志

版本 2.3.0 - 文档与配置增强

• 📚 在 CLAUDE.md 中添加了全面的项目文档
• ⚙️ 扩展了配置选项，并改进了版本检测
• 🛠️ 增强了常见问题的故障排除指南
• 🔄 详细介绍了带有实际示例的 REST API 文档
• 📝 内容管理的最佳实践指南
• 🐛 修复了从不同格式模式解析版本的问题
• 🔍 改进了带有特定版本指导的错误消息

版本 2.2.0 - 安全性与版本处理更新

• 🔒 添加了严格的写保护策略
• 🔄 增强了版本格式支持（5.* , 4.1.5, v4 等）
• 📚 将文档集成到服务器功能中
• 🚫 移除了连接提示（现在位于功能中）
• ⚡ 改进了错误处理和验证
• 🔍 添加了特定版本差异指南
• 📋 增强了服务器功能文档

版本 2.1.0

• 提高了对 Strapi v4 和 v5 的兼容性
• 移除了自动验证以支持不同版本之间的数据结构
• 增强了带有特定版本提示的错误消息
• 简化了请求处理，给予客户端更多控制权
• 更新了文档，为两个版本提供了清晰示例

功能

• 🔍 模式内省
• 🔄 带有验证的 REST API 支持
• 📸 媒体上传处理
• 🔐 JWT 认证
• 📝 内容类型管理
• 🖼️ 图像处理及格式转换
• 🌐 多服务器支持
• ✅ 自动模式验证
• 🔒 写保护策略
• 📚 集成文档
• 🔄 版本兼容性管理

安装

您可以在 Claude Desktop 配置中直接使用 npx 来使用此服务器：

{
  "mcpServers": {
    "strapi": {
      "command": "npx",
      "args": ["-y", "@bschauer/strapi-mcp-server@2.4.0"]
    }
  }
}

配置

在 ~/.mcp/strapi-mcp-server.config.json 创建一个配置文件：

{
  "myserver": {
    "api_url": "http://localhost:1337",
    "api_key": "your-jwt-token-from-strapi-admin",
    "version": "5.*" // Optional: Specify Strapi version (e.g., "5.*", "4.1.5", "v4")
  }
}

您可以通过向此文件中添加多个 Strapi 实例来进行配置。

版本配置

服务器现在支持各种版本格式：

• 通配符: "5.", "4."
• 具体: "4.1.5", "5.0.0"
• 简单: "v4", "v5"

这有助于服务器提供特定版本的指导并适当处理 API 差异。

获取 JWT 令牌

1. 登录到您的 Strapi 管理面板
2. 创建具有适当权限的 API 令牌
3. 将令牌添加到配置文件中的相应服务器名称下

使用方法

列出可用服务器

strapi_list_servers();
// Now includes version information and differences between v4 and v5

内容类型

// Get all content types from a specific server
strapi_get_content_types({
  server: "myserver",
});

// Get components with pagination
strapi_get_components({
  server: "myserver",
  page: 1,
  pageSize: 25,
});

REST API

REST API 提供了全面的 CRUD 操作，并内置了验证和特定版本处理：

// Query content with filters
strapi_rest({
  server: "myserver",
  endpoint: "api/articles",
  method: "GET",
  params: {
    filters: {
      title: {
        $contains: "search term",
      },
    },
  },
});

// Create new content
strapi_rest({
  server: "myserver",
  endpoint: "api/articles",
  method: "POST",
  body: {
    data: {
      title: "New Article",
      content: "Article content",
      category: "news",
    },
  },
});

// Update content
strapi_rest({
  server: "myserver",
  endpoint: "api/articles/123",
  method: "PUT",
  body: {
    data: {
      title: "Updated Title",
      content: "Updated content",
    },
  },
});

// Delete content
strapi_rest({
  server: "myserver",
  endpoint: "api/articles/123",
  method: "DELETE",
});

媒体上传

// Upload image with automatic optimization
strapi_upload_media({
  server: "myserver",
  url: "https://example.com/image.jpg",
  format: "webp",
  quality: 80,
  metadata: {
    name: "My Image",
    caption: "Image Caption",
    alternativeText: "Alt Text",
  },
});

版本差异 (v4 vs v5)

服务器自动处理的不同 Strapi 版本之间的主要差异：

v4

• 使用数字 ID
• 嵌套属性结构
• 响应中的数据包装
• 传统的 REST 模式
• 外部 i18n 插件

v5

• 文档式 ID
• 扁平数据结构
• 直接访问属性
• 增强的 JWT 安全性
• 集成的 i18n 支持
• 新的文档服务 API

安全特性

写保护策略

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

• 所有写操作都需要明确授权
• 受保护的操作包括：
  • POST（创建）
  • PUT（更新）
  • DELETE
  • 媒体上传
• 每个操作都会被记录并验证

最佳实践

1. 总是先使用 strapi_get_content_types 检查模式
2. 对于端点使用正确的复数/单数形式
3. 在查询中包含错误处理
4. 在上传前验证 URL
5. 从最小查询开始，仅在需要时添加填充
6. 更新时始终包含完整的数据对象
7. 使用过滤器优化查询性能
8. 利用内置的模式验证
9. 检查操作的版本兼容性
10. 遵循写保护策略指南

REST API 技巧

过滤

// Filter by field value
params: {
  filters: {
    title: "Exact Match";
  }
}

// Contains filter
params: {
  filters: {
    title: {
      $contains: "partial";
    }
  }
}

// Multiple conditions
params: {
  filters: {
    $and: [{ category: "news" }, { published: true }];
  }
}

排序

params: {
  sort: ["createdAt:desc"];
}

分页

params: {
  pagination: {
    page: 1,
    pageSize: 25
  }
}

填充

// Basic request without population
params: {
}

// Selective population when needed
params: {
  populate: ["category"];
}

// Detailed population with field selection
params: {
  populate: {
    category: {
      fields: ["name", "slug"];
    }
  }
}

故障排除

常见问题及解决方案：

1. 404 错误

   • 检查端点的复数/单数形式
   • 验证内容类型是否存在
   • 确保正确的 API URL
   • 检查是否使用了正确的 ID 格式（数字与文档式）

2. 身份验证问题

   • 验证 JWT 令牌是否有效
   • 检查令牌权限
   • 确保令牌未过期

3. 版本相关问题

   • 验证配置中的版本说明
   • 检查数据结构是否匹配版本
   • 查看版本差异文档

4. 写保护错误

   • 确保操作已授权
   • 检查操作是否受保护
   • 验证请求是否遵循安全策略

贡献

欢迎贡献！请随时提交 Pull Request。

许可证

MIT