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.5.0"]
    }
  }
}

配置

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

{
  "myserver": {
    "api_url": "http://localhost:1337",
    "api_key": "your-jwt-token-from-strapi-admin",
    "version": "5.*" // 可选：指定 Strapi 版本（例如 "5.*", "4.1.5", "v4"）
  }
}

您可以通过向此文件添加多个 Strapi 实例来配置多个服务器。

版本配置

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

通配符："5.", "4."
特定版本："4.1.5", "5.0.0"
简单版本："v4", "v5"

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

获取 JWT 令牌

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

使用

列出可用服务器

strapi_list_servers();
// 现在包括版本信息以及 v4 和 v5 之间的差异

内容类型

// 从特定服务器获取所有内容类型
strapi_get_content_types({
  server: "myserver",
});

// 分页获取组件
strapi_get_components({
  server: "myserver",
  page: 1,
  pageSize: 25,
});

REST API

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

// 使用过滤器查询内容
strapi_rest({
  server: "myserver",
  endpoint: "api/articles",
  method: "GET",
  params: {
    filters: {
      title: {
        $contains: "search term",
      },
    },
  },
});

// 创建新内容
strapi_rest({
  server: "myserver",
  endpoint: "api/articles",
  method: "POST",
  body: {
    data: {
      title: "New Article",
      content: "Article content",
      category: "news",
    },
  },
});

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

// 删除内容
strapi_rest({
  server: "myserver",
  endpoint: "api/articles/123",
  method: "DELETE",
});

媒体上传

// 上传图像并自动优化
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
- 媒体上传
每个操作都会被记录和验证

最佳实践

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

REST API 提示

过滤

// 按字段值过滤
params: {
  filters: {
    title: "Exact Match";
  }
}

// 包含过滤器
params: {
  filters: {
    title: {
      $contains: "partial";
    }
  }
}

// 多个条件
params: {
  filters: {
    $and: [{ category: "news" }, { published: true }];
  }
}

排序

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

分页

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

填充

// 基本请求，不填充
params: {
}

// 需要时选择性填充
params: {
  populate: ["category"];
}

// 详细填充，选择字段
params: {
  populate: {
    category: {
      fields: ["name", "slug"];
    }
  }
}

故障排除

常见问题及解决方案：

404 错误
- 检查端点的复数/单数形式
- 验证内容类型是否存在
- 确保 API URL 正确
- 检查是否使用了正确的 ID 格式（数字 vs 基于文档）
认证问题
- 验证 JWT 令牌是否有效
- 检查令牌权限
- 确保令牌未过期
版本相关问题
- 验证配置中的版本指定
- 检查数据结构是否与版本匹配
- 查看版本差异文档
写保护错误
- 确保操作已授权
- 检查操作是否受保护
- 验证请求是否符合安全策略

贡献

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

许可证

MIT