Strapi MCP Server

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 文件。

快速设置：

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": "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）

身份验证优先级

服务器按以下顺序对身份验证方法进行优先级排序：

1. 管理员电子邮件和密码(STRAPI_ADMIN_EMAIL, STRAPI_ADMIN_PASSWORD)
2. API代币(STRAPI_API_TOKEN)

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

获取Strapi证书

• 管理员凭据： 使用现有超级管理员的电子邮件和密码，或在Strapi管理面板（设置>管理面板>用户）中创建专用管理员用户。
• API令牌： （可选回退）

1. 登录您的Strapi管理面板
2. 前往“设置”>“API令牌”
3. 点击“新建API代币”
4. 设置名称、描述和令牌类型（最好是“完全访问”）
5. 复制生成的令牌并在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"
      }
    }
  }
)

访问资源