Strapi MCP

Strapi MCP

一个用于 Strapi CMS 的 MCP 服务，通过 Model Context Protocol 提供对内容类型和条目的访问。

概述

此 MCP 服务可与任何 Strapi CMS 实例集成，提供：

• 将 Strapi 内容类型作为资源访问
• 在 Strapi 中创建和更新内容类型的工具
• 管理内容条目（创建、读取、更新、删除）的工具
• 对开发模式下的 Strapi 的支持
• 健壮的错误处理，提供清晰的诊断和故障排除指导
• 配置验证，防止常见的设置问题

设置

环境变量

建议在项目根目录使用 .env 文件来存储你的凭据。

• STRAPI_URL：你的 Strapi 实例的 URL（默认：http://localhost:1337）
• STRAPI_ADMIN_EMAIL：Strapi 管理员用户的电子邮件地址（推荐用于完整功能，尤其是 schema 访问）。
• STRAPI_ADMIN_PASSWORD：Strapi 管理员用户的密码（推荐）。
• STRAPI_API_TOKEN：（可选回退）一个 API 令牌。如果未提供管理员凭据，可以使用，但权限可能有限。
• STRAPI_DEV_MODE：设置为 "true" 以启用开发模式功能（默认为 false）。

示例 .env 文件：

STRAPI_URL=http://localhost:1337
[email protected]
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

运行

推荐方法（使用 Cursor MCP 配置）：

对于 Cursor 用户，在 ~/.cursor/mcp.json 文件中配置 strapi-mcp 服务：

"strapi-mcp": {
  "command": "npx",
  "args": ["strapi-mcp"], 
  "env": {
    "STRAPI_URL": "http://localhost:1337",
    "STRAPI_ADMIN_EMAIL": "[email protected]",
    "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": "[email protected]",
    "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 [email protected]
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

功能

• 列出并读取内容类型
• 获取、创建、更新和删除条目
• 上传媒体文件
• 连接和断开关系
• 获取内容类型 schema

更新日志

0.2.3 - 2025-07-25

• 严重修复： 修复了关系工具中的超时问题 - connect_relation 和 disconnect_relation 现在能正确处理验证错误，而不是超时
• 改进错误处理： 所有验证错误现在都会返回正确的错误信息，而不会导致工具超时

0.2.2 - 2025-07-25

• 增强关系工具： 改进了 connect_relation 和 disconnect_relation 的错误处理，提供详细的验证和故障排查信息
• 修复 CREATE_COMPONENT： 修复了参数验证 bug - 现在能正确验证各个参数，而不是单个对象
• 更好的错误诊断： 为无效关系字段、不存在的条目和格式错误的 ID 添加了具体的错误信息
• 全部 20 个工具现在均 100% 正常工作，具备健壮的错误处理和验证

0.2.0 - 2025-07-25

• 严重 bug 修复： 修复了 validateStrapiConnection 导致 "undefined response status" 错误的问题
• 解决 MCP 连接问题： 修复了 AI 工具 "绿灯但无法正常工作" 的问题
• 改进错误处理： 更好的连接验证逻辑，正确处理 admin 认证
• 如果 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

• 重大 bug 修复： 当无法获取内容类型或条目时，用描述性错误信息替换静默失败
• 添加配置验证： 检测占位符 API token 并以有用的错误信息退出
• 添加连接验证： 在尝试操作之前测试 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 删除现有内容类型
• 增强 Admin 认证： 为所有 API 操作提供更好的错误处理和 token 管理

0.1.6

• 添加 create_content_type 工具： 允许通过 Content-Type Builder API 创建新的内容类型（需要 admin 凭据）。
• 优先使用 Admin 凭据： 更新逻辑，优先使用 admin 邮箱/密码来获取内容类型和 schema，提高可靠性。
• 更新文档： 阐明了认证方法并推荐了运行流程。

0.1.5

• 通过多种回退方法改进内容类型发现
• 添加更健壮的错误处理和日志记录
• 增强内容类型的 schema 推断

0.1.4

• 通过更具体的错误代码改进错误处理
• 添加 ResourceNotFound 和 AccessDenied 错误代码
• 为常见 API 错误提供更好的错误信息

0.1.3

• 首次公开发布

许可证

MIT

strapi-mcp MCP 服务

适用于你的 Strapi CMS 的 MCP 服务

这是一个基于 TypeScript 的 MCP 服务，可与 Strapi CMS 集成。它通过 MCP 协议提供对 Strapi 内容类型和条目的访问，让你可以：

• 将 Strapi 内容类型作为资源访问
• 创建、读取、更新和删除内容条目
• 通过 MCP 工具管理你的 Strapi 内容

功能

资源

• 通过 strapi://content-type/ URI 列出并访问内容类型
• 每个内容类型都会以 JSON 形式公开其条目
• 使用 Application/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 - 获取特定内容类型的 schema（字段、类型、关系）。
• connect_relation - 将相关条目连接到某个条目的关系字段。
• disconnect_relation - 断开相关条目与某个条目的关系字段的连接。
• create_content_type - 使用 Content-Type Builder API 创建新的内容类型（需要管理员权限）。
• publish_entry - 发布特定条目。
• unpublish_entry - 取消发布特定条目。
• list_components - 列出 Strapi 中所有可用的组件。
• get_component_schema - 获取特定组件的 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 服务的详细分步说明，请参阅 DEPLOYMENT.md 文件。

快速设置：

1. 构建服务：npm run build
2. 配置你的 Strapi 实例并获取 API 令牌
3. 将服务配置添加到 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": "[email protected]",
        "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": "[email protected]",
        "STRAPI_ADMIN_PASSWORD": "your_admin_password"
      }
    }
  }
}

环境变量

• STRAPI_URL（可选）：你的 Strapi 实例的 URL（默认为 http://localhost:1337）
• STRAPI_ADMIN_EMAIL 和 STRAPI_ADMIN_PASSWORD（推荐）：Strapi 管理员用户的凭据。获取内容类型 schema 等完整功能需要此项。
• STRAPI_API_TOKEN（可选回退方案）：你的 Strapi API 令牌。在未提供管理员凭据时可以使用，但功能可能会因令牌权限而受到限制。
• STRAPI_DEV_MODE（可选）：设置为 "true" 以启用开发模式功能（默认为 false）

认证优先级

服务按以下顺序优先使用认证方式：

1. 管理员邮箱和密码（STRAPI_ADMIN_EMAIL、STRAPI_ADMIN_PASSWORD）
2. API 令牌（STRAPI_API_TOKEN）

强烈建议使用管理员凭据以获得最佳效果。

获取 Strapi 凭据

• 管理员凭据： 使用现有超级管理员的邮箱和密码，或在你的 Strapi 管理面板中创建一个专用管理员用户（Settings > Administration Panel > Users）。
• API 令牌：（可选回退方案）

1. 登录你的 Strapi 管理面板
2. 前往 Settings > API Tokens
3. 点击 "Create new API Token"
4. 设置名称、描述和令牌类型（最好选择 "Full access"）
5. 复制生成的令牌，并在你的 MCP 服务配置中使用它

故障排除

常见问题及解决方案：

1. 占位符 API 令牌错误

[Error] STRAPI_API_TOKEN appears to be a placeholder value...

解决方案： 将 "strapi" 或 "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
• 检查 STRAPI_URL 中的 URL 是否正确
• 验证你的数据库（MySQL/PostgreSQL）正在运行

3. 认证失败

Cannot connect to Strapi instance: Authentication failed. Check your API token or admin credentials.

解决方案：

• 验证你的 API 令牌具有适当的权限（最好是 "Full access"）
• 检查管理员邮箱/密码是否正确
• 确保管理员存在且处于活动状态

4. 文件上传导致上下文窗口溢出

Error: Context window overflow due to large base64 strings

问题： Base64 编码的文件可能非常大（即使是小图片也可能有 50-100KB），从而导致上下文窗口溢出。

解决方案：

• 对于大于约 500KB 的文件，使用 upload_media_from_path 而不是 upload_media
• 在上传前减小文件大小（压缩图片、降低分辨率）
• 使用更小的文件 - upload_media 工具有 1MB 的 base64 限制（约 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 令牌，确保其具有 "Full access" 权限
• 如果使用受限 API 令牌，检查内容类型是否允许公共访问

调试

由于 MCP 服务通过 stdio 通信，调试可能具有挑战性。我们建议使用 MCP Inspector，它可作为一个包脚本使用：

npm run inspector

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"
      }
    }
  }
)

访问资源