Strapi MCP
Strapi CMS的MCP服务器，通过模型上下文协议提供对内容类型和条目的访问。
概述
此MCP服务器与任何Strapi CMS实例集成，以提供：
- 访问Strapi内容类型作为资源
- 在Strapi中创建和更新内容类型的工具
- 管理内容条目的工具（创建、读取、更新、删除）
- 开发模式支持Strapi
- 稳健的错误处理 具有明确的诊断和故障排除指南
- 配置验证 防止常见的设置问题
设置
环境变量
建议使用 .env 项目根目录中的文件来存储您的凭据。
STRAPI_URL：Strapi实例的URL（默认值：http://localhost:1337)STRAPI_ADMIN_EMAIL：Strapi管理员用户的电子邮件地址（建议用于完整功能，特别是模式访问）。STRAPI_ADMIN_PASSWORD：Strapi管理员用户的密码（推荐）。STRAPI_API_TOKEN：（可选回退）API令牌。如果未提供管理员凭据，则可以使用，但权限可能有限。STRAPI_DEV_MODE：设置为"true"启用开发模式功能（默认为false).
示例 .env 文件：
STRAPI_URL=http://localhost:1337
STRAPI_ADMIN_EMAIL=your_admin_email@example.com
STRAPI_ADMIN_PASSWORD=your_admin_password
# STRAPI_API_TOKEN=your_api_token_here # Optional重要提示：
- 添加
.env到你的.gitignore文件以避免提交凭据 - 避免占位符值，如
"strapi_token"-服务器验证并拒绝常见占位符
安装
从npm安装（推荐）
npm install strapi-mcp从源代码安装（开发）
有关最新开发功能：
git clone https://github.com/l33tdawg/strapi-mcp.git
cd strapi-mcp
npm install
npm run build跑步
推荐方法（使用光标MCP配置）：
对于Cursor用户，请在您的 ~/.cursor/mcp.json 文件：
"strapi-mcp": {
"command": "npx",
"args": ["strapi-mcp"],
"env": {
"STRAPI_URL": "http://localhost:1337",
"STRAPI_ADMIN_EMAIL": "your_admin_email@example.com",
"STRAPI_ADMIN_PASSWORD": "your_admin_password"
}
}如果从源代码安装，请使用直接路径：
"strapi-mcp": {
"command": "node",
"args": ["/path/to/strapi-mcp/build/index.js"],
"env": {
"STRAPI_URL": "http://localhost:1337",
"STRAPI_ADMIN_EMAIL": "your_admin_email@example.com",
"STRAPI_ADMIN_PASSWORD": "your_admin_password"
}
}使用strapi mcp工具时，Cursor将自动管理服务器生命周期。
替代方法（使用 .env 文件）：
确保您已经构建了项目(npm run build).然后使用Node.js v20.6.0+运行服务器 --env-file 标志：
node --env-file=.env build/index.js替代方案（直接使用环境变量）：
export STRAPI_URL=http://localhost:1337
export STRAPI_ADMIN_EMAIL=your_admin_email@example.com
export STRAPI_ADMIN_PASSWORD=your_admin_password
# export STRAPI_API_TOKEN=your-api-token # Optional fallback
export STRAPI_DEV_MODE=true # optional
# Run the globally installed package (if installed via npm install -g)
strapi-mcp
# Or run the local build directly
node build/index.js特性
- 列出并阅读内容类型
- 获取、创建、更新和删除条目
- 上传媒体文件
- 连接和断开关系
- 获取内容类型架构
更新日志
0.2.3 - 2025-07-25
- 关键修复： 修复了关系工具中的超时问题-connect_relation和disconnect_relation现在可以正确处理验证错误，而不是超时
- 改进的错误处理： 现在，所有验证错误都会返回正确的错误消息，而不会导致工具超时
0.2.2 - 2025-07-25
- 增强的关系工具： 改进了错误处理
connect_relation和disconnect_relation带有详细的验证和故障排除消息 - 已修复CREATE_COMPONENT： 修复了参数验证错误-现在可以正确验证单个参数，而不是单个对象
- 更好的错误诊断： 为无效的关系字段、不存在的条目和格式错误的ID添加了特定的错误消息
- 所有20个工具现在都100%工作，具有强大的错误处理和验证功能
0.2.0 - 2025-07-25
- 关键错误修复： 修复了validateScrapiConnection导致“未定义响应状态”错误的问题
- 已解决MCP连接问题： 修复了AI工具的“绿灯但不起作用”问题
- 改进的错误处理： 通过适当的管理员身份验证处理，实现更好的连接验证逻辑
- 如果用户在使用AI工具时遇到MCP连接问题，应更新到此版本
0.1.9 - 2025-07-02
- 上下文窗口溢出修复： 增加了大小限制和响应过滤，以防止base64文件淹没上下文窗口
- 新工具： 添加
upload_media_from_path-从本地文件路径上传文件（最大10MB）以避免base64上下文问题 - 增强的UPLOAD_MEDIA： 添加了1MB base64大小限制（约750KB文件），并明确显示了有关上下文溢出的错误消息
- 改进的日志记录： 截断日志中的base64数据，以防止日志垃圾邮件和上下文溢出
- 响应过滤： 自动从API响应中筛选大型base64字符串，以防止回声溢出
0.1.8 - 2025-06-12
- 主要错误修复： 当无法获取内容类型或条目时，用描述性错误消息替换无声故障
- 添加配置验证： 检测占位符API令牌并退出并显示有用的错误消息
- 添加连接验证： 在尝试使用特定错误诊断进行操作之前测试Strapi连接
- 增强的错误处理： 全面的错误诊断，区分合法的空集合与实际错误
- 改进的故障排除： 所有错误消息都包括解决常见配置问题的具体步骤
0.1.7 - 2025-05-17
- 添加
publish_entry和unpublish_entry工具： 完整的内容生命周期管理 - 新增组件管理：
list_components,get_component_schema,create_component,update_component - 添加
delete_content_type工具： 通过content-Type Builder API删除现有内容类型 - 增强的管理员身份验证： 为所有API操作提供更好的错误处理和令牌管理
0.1.6
- 添加
create_content_type工具： 允许通过content-Type Builder API创建新的内容类型（需要管理员凭据）。 - 优先管理员凭据： 更新了逻辑，更喜欢管理员电子邮件/密码来获取内容类型和模式，提高了可靠性。
- 更新文件： 阐明了身份验证方法和推荐的运行过程。
0.1.5
- 通过多种回退方法改进了内容类型发现
- 添加了更强大的错误处理和日志记录
- 增强内容类型的模式推理
0.1.4
- 使用更具体的错误代码改进错误处理
- 添加
ResourceNotFound和AccessDenied错误代码 - 针对常见API错误提供更好的错误消息
0.1.3
- 首次公开发布
许可证
麻省理工学院
strapi mcp mcp服务器
Strapi CMS的MCP服务器
这是一个基于TypeScript的MCP服务器，与Strapi CMS集成。它通过MCP协议提供对Strapi内容类型和条目的访问，允许您：
- 访问Strapi内容类型作为资源
- 创建、读取、更新和删除内容条目
- 通过MCP工具管理您的Strapi内容
特性
资源
- 通过以下方式列出和访问内容类型
strapi://content-type/URI - 每种内容类型都以JSON形式公开其条目
- 用于结构化内容访问的应用程序/JSON mime类型
工具
list_content_types-列出Strapi中所有可用的内容类型get_entries-通过可选的筛选、分页、排序和关系填充来获取特定内容类型的条目get_entry-按ID获取特定条目create_entry-为内容类型创建新条目update_entry-更新现有条目delete_entry-删除条目upload_media-将媒体文件上传到Strapi（由于base64上下文限制，最大约750KB的文件）upload_media_from_path-从本地文件路径上传媒体文件（最大10MB，避免上下文溢出）get_content_type_schema-获取特定内容类型的模式（字段、类型、关系）。connect_relation-将相关条目连接到条目的关系字段。disconnect_relation-断开相关条目与条目关系字段的连接。create_content_type-使用content-type Builder API创建新的内容类型（需要管理员权限）。publish_entry-发布特定条目。unpublish_entry-取消发布特定条目。list_components-列出Strapi中的所有可用组件。get_component_schema-获取特定组件的架构。create_component-创建新组件。update_component-更新现有组件。
高级功能
过滤、分页和排序
这 get_entries 该工具支持高级查询选项：
{
"contentType": "api::article.article",
"filters": {
"title": {
"$contains": "hello"
}
},
"pagination": {
"page": 1,
"pageSize": 10
},
"sort": ["title:asc", "createdAt:desc"],
"populate": ["author", "categories"]
}资源URI
可以使用各种URI格式访问资源：
strapi://content-type/api::article.article-获取所有文章strapi://content-type/api::article.article/1-获取ID为1的文章strapi://content-type/api::article.article?filters={"title":{"$contains":"hello"}}-获取已筛选的文章
发布和取消发布内容
这 publish_entry 和 unpublish_entry 工具提供对内容生命周期的控制：
{
"contentType": "api::article.article",
"id": "1"
}这些工具使用管理API路径来发布/取消发布操作，并提供直接更新 publishedAt 字段（如果管理员权限不可用）。
组件管理
Strapi组件可以使用以下工具进行管理：
list_components：获取所有可用组件get_component_schema：查看特定组件的结构create_component：使用指定字段创建新组件update_component：修改现有组件
创建组件的示例：
{
"componentData": {
"displayName": "Security Settings",
"category": "security",
"icon": "shield",
"attributes": {
"enableTwoFactor": {
"type": "boolean",
"default": false
},
"passwordExpiration": {
"type": "integer",
"min": 0
}
}
}
}发展
安装依赖项：
npm install构建服务器：
npm run build对于自动重建的开发：
npm run watch安装
有关如何部署和测试此MCP服务器的详细分步说明，请参阅 部署.md 文件。
快速设置：
- 构建服务器：
npm run build - 配置您的Strapi实例并获得API令牌
- 将服务器配置添加到Claude Desktop：
在MacOS上： ~/Library/Application Support/Claude/claude_desktop_config.json 在Windows上： %APPDATA%/Claude/claude_desktop_config.json
{
"mcpServers": {
"strapi-mcp": {
"command": "npx",
"args": ["strapi-mcp"],
"env": {
"STRAPI_URL": "http://localhost:1337",
"STRAPI_ADMIN_EMAIL": "your_admin_email@example.com",
"STRAPI_ADMIN_PASSWORD": "your_admin_password"
}
}
}
}如果从源代码安装，请使用直接路径：
{
"mcpServers": {
"strapi-mcp": {
"command": "/path/to/strapi-mcp/build/index.js",
"env": {
"STRAPI_URL": "http://localhost:1337",
"STRAPI_ADMIN_EMAIL": "your_admin_email@example.com",
"STRAPI_ADMIN_PASSWORD": "your_admin_password"
}
}
}
}环境变量
STRAPI_URL（可选）：Strapi实例的URL（默认为http://localhost:1337)STRAPI_ADMIN_EMAIL&STRAPI_ADMIN_PASSWORD（推荐）：Strapi管理员用户的凭据。获取内容类型模式等完整功能所需。STRAPI_API_TOKEN（可选回退）：您的Strapi API代币。如果未提供管理员凭据，则可以使用，但功能可能会根据令牌权限受到限制。STRAPI_DEV_MODE（可选）：设置为“true”以启用开发模式功能（默认为false）
身份验证优先级
服务器按以下顺序对身份验证方法进行优先级排序：
- 管理员电子邮件和密码(
STRAPI_ADMIN_EMAIL,STRAPI_ADMIN_PASSWORD) - API代币(
STRAPI_API_TOKEN)
强烈建议使用管理员凭据以获得最佳结果。
获取Strapi证书
- 管理员凭据： 使用现有超级管理员的电子邮件和密码，或在Strapi管理面板（设置>管理面板>用户）中创建专用管理员用户。
- API令牌： （可选回退）
- 登录您的Strapi管理面板
- 前往“设置”>“API令牌”
- 点击“新建API代币”
- 设置名称、描述和令牌类型（最好是“完全访问”）
- 复制生成的令牌并在MCP服务器配置中使用
故障排除
常见问题及解决方案：
1. 占位符API令牌错误
[Error] STRAPI_API_TOKEN appears to be a placeholder value...解决方案： 替换 "strapi_token" 或 "your-api-token-here" 从您的Strapi管理面板使用真正的API令牌。
2. 连接被拒绝错误
Cannot connect to Strapi instance: Connection refused. Is Strapi running at http://localhost:1337?解决方案：
- 确保Strapi正在运行：
npm run develop或yarn develop - 检查URL是否在
STRAPI_URL是正确的 - 验证您的数据库（MySQL/PostgreSQL）是否正在运行
3. 认证失败
Cannot connect to Strapi instance: Authentication failed. Check your API token or admin credentials.解决方案：
- 验证您的API令牌是否具有适当的权限（最好是“完全访问”）
- 检查管理员电子邮件/密码是否正确
- 确保管理员用户存在并且处于活动状态
4. 文件上传导致上下文窗口溢出
Error: Context window overflow due to large base64 strings问题： Base64编码的文件可能非常大（即使是小图像也可能是50-100KB的文本），导致上下文窗口溢出。
解决：
- 使用
upload_media_from_path而不是upload_media对于大于~500KB的文件 - 减小文件大小 上传前（压缩图像，降低分辨率）
- 使用较小的文件 -the
upload_media该工具的base64限制为1MB（约750KB文件）
5. 虚假内容类型 (api::data.data, api::error.error)
这个问题已经 在v0.1.8中固定。如果您仍然看到这些，则可能使用的是旧版本。
6. 空结果与错误
从v0.1.8开始，服务器现在可以清楚地区分以下内容：
- 空集合 （内容类型存在，但没有条目）→ 退货
{"data": [], "meta": {...}} - 实际误差 （内容类型不存在、身份验证失败等）→ 在故障排除步骤中出现描述性错误
7. 权限错误
Access forbidden. Your API token may lack necessary permissions.解决方案：
- 使用管理员凭据而不是API令牌以获得完整功能
- 如果使用API令牌，请确保其具有“完全访问”权限
- 如果使用有限的API令牌，请检查内容类型是否允许公共访问
调试
由于MCP服务器通过stdio进行通信，调试可能具有挑战性。我们建议使用 MCP检查员，可作为包脚本使用：
npm run inspector检查器将提供一个URL，用于访问浏览器中的调试工具。
使用示例
配置并运行MCP服务器后，您可以将其与Claude一起使用，与Strapi CMS进行交互。以下是一些示例：
列出内容类型
use_mcp_tool(
server_name: "strapi-mcp",
tool_name: "list_content_types",
arguments: {}
)获取条目
use_mcp_tool(
server_name: "strapi-mcp",
tool_name: "get_entries",
arguments: {
"contentType": "api::article.article",
"filters": {
"title": {
"$contains": "hello"
}
},
"pagination": {
"page": 1,
"pageSize": 10
},
"sort": ["title:asc"]
}
)创建条目
use_mcp_tool(
server_name: "strapi-mcp",
tool_name: "create_entry",
arguments: {
"contentType": "api::article.article",
"data": {
"title": "My New Article",
"content": "This is the content of my article.",
"publishedAt": "2023-01-01T00:00:00.000Z"
}
}
)上传媒体
方法1:Base64上传（仅限小文件）
use_mcp_tool(
server_name: "strapi-mcp",
tool_name: "upload_media",
arguments: {
"fileData": "base64-encoded-data-here",
"fileName": "image.jpg",
"fileType": "image/jpeg"
}
)方法2：文件路径上传（建议用于较大的文件）
use_mcp_tool(
server_name: "strapi-mcp",
tool_name: "upload_media_from_path",
arguments: {
"filePath": "/path/to/your/image.jpg"
}
)连接关系
use_mcp_tool(
server_name: "strapi-mcp",
tool_name: "connect_relation",
arguments: {
"contentType": "api::article.article",
"id": "1",
"relationField": "authors",
"relatedIds": [2, 3]
}
)断开关系
use_mcp_tool(
server_name: "strapi-mcp",
tool_name: "disconnect_relation",
arguments: {
"contentType": "api::article.article",
"id": "1",
"relationField": "authors",
"relatedIds": [3]
}
)创建内容类型
use_mcp_tool(
server_name: "strapi-mcp-local",
tool_name: "create_content_type",
arguments: {
"displayName": "My New Product",
"singularName": "product",
"pluralName": "products",
"kind": "collectionType",
"description": "Represents products in the store",
"draftAndPublish": true,
"attributes": {
"name": { "type": "string", "required": true },
"description": { "type": "text" },
"price": { "type": "decimal", "required": true },
"stock": { "type": "integer" }
}
}
)更新内容类型
use_mcp_tool(
server_name: "strapi-mcp-local",
tool_name: "update_content_type",
arguments: {
"contentType": "api::speaker.speaker",
"attributes": {
"isHighlightSpeaker": {
"type": "boolean",
"default": false
},
"newTextField": {
"type": "string"
}
}
}
)访问资源