MCP 服务器

5.47.0

Page summary:
Strapi 包含一个内置的模型上下文协议 (MCP) 服务器。一旦启用，它允许 AI 客户端通过 Strapi 的内容管理器直接创建、读取、更新、删除、发布和取消发布内容。所有操作都受管理员令牌权限的控制。
🌐 Strapi includes a built-in Model Context Protocol (MCP) server. Once enabled, it lets AI clients create, read, update, delete, publish, and unpublish content directly through Strapi's Content Manager. All operations are gated by Admin token permissions.

MCP 服务器向 AI 客户端（如 Claude Desktop、Claude Code、Cursor 或任何兼容 MCP 的工具）提供一套内容管理工具。连接到 MCP 服务器的 AI 客户端可以例如创建博客文章、列出最近的条目或发布页面。可用的工具取决于用于认证的管理员令牌所授予的权限。

🌐 The MCP server exposes a set of content management tools to AI clients such as Claude Desktop, Claude Code, Cursor, or any MCP-compatible tool. An AI client connected to the MCP server can, for example, create a blog article, list recent entries, or publish a page. Which tools are available depends on the permissions granted to the Admin token used for authentication.

计划

免费功能

角色与权限

管理员（令牌创建者）

激活

服务器配置

环境

可在开发和生产环境中使用

配置

🌐 Configuration

在首次使用之前，必须对 Strapi MCP 服务器进行：

🌐 Before first use, the Strapi MCP server must be:

通过服务器配置文件启用，并使用在管理面板中创建的管理员令牌进行身份验证
已连接到你的 AI 客户端。

基于代码的 Strapi 配置

🌐 Strapi code-based configuration

通过将 mcp 对象添加到服务器配置文件中来启用 MCP 服务器：

🌐 Enable the MCP server by adding the mcp object to the server configuration file:

JavaScript
TypeScript

config/server.js
module.exports = ({ env }) => ({
  host: env('HOST', '0.0.0.0'),
  port: env.int('PORT', 1337),
  app: {
    keys: env.array('APP_KEYS'),
  },
  mcp: {
    enabled: true,
  },
});

config/server.ts
import type { Core } from '@strapi/strapi';

const config = ({ env }: Core.Config.Shared.ConfigParams): Core.Config.Server => ({
  host: env('HOST', '0.0.0.0'),
  port: env.int('PORT', 1337),
  app: {
    keys: env.array('APP_KEYS'),
  },
  mcp: {
    enabled: true,
  },
});
export default config;

设置完成后，重启 Strapi。MCP 端点将在你的 Strapi 服务器上通过 /mcp 可用（例如，http://localhost:1337/mcp）。

🌐 Once the setting is in place, restart Strapi. The MCP endpoint becomes available at /mcp on your Strapi server (e.g., http://localhost:1337/mcp).

高级选项

🌐 Advanced options

可以将以下可选键添加到 mcp 配置对象中：

🌐 The following optional keys can be added to the mcp configuration object:

选项	类型	默认值	描述
`enabled`	布尔值	`false`	启用或禁用 MCP 服务器。
`connectTimeoutMs`	数字	`5000`	内部 MCP 传输在请求中止前的最大连接时间（毫秒）。
`requestTimeoutMs`	数字	`60000`	单个 MCP 请求在超时前完成的最大时间（毫秒）。

config/server.js
mcp: {
  enabled: true,
  connectTimeoutMs: 10000, // 10 seconds
  requestTimeoutMs: 120000, // 2 minutes
},

Strapi 管理面板配置

🌐 Strapi admin panel configuration

MCP 服务器使用管理员令牌对请求进行身份验证。每个 MCP 会话的权限范围取决于用来连接的令牌：

🌐 The MCP server authenticates requests using Admin tokens. Each MCP session is scoped to the permissions of the token used to connect:

创建新的管理员令牌（请参阅管理员令牌功能页面上的创建管理员令牌）。
复制令牌值。在配置 AI 客户端时你将需要它。

令牌的权限决定了哪些 MCP 工具对 AI 客户端可见。例如，如果令牌仅在 Article 内容类型上授予 read，AI 客户端将只看到文章的列出和阅读工具。

🌐 The token's permissions determine which MCP tools are exposed to the AI client. For instance, if the token only grants read on an Article content-type, the AI client will only see listing and reading tools for articles.

AI客户端配置

🌐 AI client configuration

一旦你通过服务器配置文件启用了 MCP 服务器，并在管理面板中创建了管理员令牌，就将你的 AI 客户端连接到 Strapi MCP 服务器。

🌐 Once you have enabled the MCP server through the server configuration file and created an Admin token in the admin panel, connect your AI client to the Strapi MCP server.

Note

http://localhost:1337/ 在本页面的配置示例中使用。如果你的 Strapi 服务器托管在其他网址或端口，请相应地更新代码。

连接 Claude 桌面

🌐 Connecting Claude Desktop

打开 Claude Desktop 的配置文件。位置因你的系统而异：

🌐 Open Claude Desktop's configuration file. The location varies depending on your system:

操作系统	文件位置
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`

Tip

你也可以从 Claude 的设置中打开 Claude Desktop 的配置文件：进入设置 > 桌面应用 > 开发者，然后点击 编辑配置 按钮。

🌐 You can also open the configuration file for Claude Desktop from Claude's settings: go to Settings > Desktop app > Developer, then click on the Edit config button.

将 Strapi MCP 服务器添加到 Claude 的配置文件中，如下例所示，将 YOUR_ADMIN_TOKEN 替换为从 Strapi 管理面板配置中复制的管理员令牌值：

🌐 Add the Strapi MCP server to Claude's configuration file, as in the following example, replacing YOUR_ADMIN_TOKEN with the Admin token value copied from the Strapi admin panel configuration:

claude_desktop_config.json
{
  "mcpServers": {
    "strapi-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:1337/mcp",
        "--header",
        "Authorization: Bearer YOUR_ADMIN_TOKEN"
      ]
    }
  }
}

重启 Claude 桌面以使更改生效。

🌐 Restart Claude Desktop for the changes to take effect.

连接Claude代码

🌐 Connecting Claude Code

运行以下命令，将 YOUR_ADMIN_TOKEN 替换为从 Strapi 管理面板配置复制的管理员令牌值：

🌐 Run the following command, replacing YOUR_ADMIN_TOKEN with the Admin token value copied from the Strapi admin panel configuration:

terminal
claude mcp add strapi-mcp --transport http http://localhost:1337/mcp -H "Authorization: Bearer YOUR_ADMIN_TOKEN"

重启 Claude 代码，然后运行 /mcp 以确认 strapi-mcp 报告为已连接。

🌐 Restart Claude Code, then run /mcp to confirm strapi-mcp reports as connected.

连接光标

🌐 Connecting Cursor

将服务器添加到你的 .cursor/mcp.json 文件中：

🌐 Add the server to your .cursor/mcp.json file:

.cursor/mcp.json
{
  "mcpServers": {
    "strapi-mcp": {
      "type": "streamable-http",
      "url": "http://localhost:1337/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_ADMIN_TOKEN"
      }
    }
  }
}

连接帆板

🌐 Connecting Windsurf

将服务器添加到你的 ~/.codeium/windsurf/mcp_config.json 文件中：

🌐 Add the server to your ~/.codeium/windsurf/mcp_config.json file:

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "strapi-mcp": {
      "serverUrl": "http://localhost:1337/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_ADMIN_TOKEN"
      }
    }
  }
}

连接其他MCP客户端

🌐 Connecting other MCP clients

任何支持 MCP 可流式 HTTP 传输的客户端都可以连接。通用配置如下：

🌐 Any client that supports the MCP Streamable HTTP transport can connect. The generic configuration is as follows:

设置	值
传输类型	`streamable-http`
URL	`http://localhost:1337/mcp`（将主机和端口调整为你的 Strapi 实例）
授权头	`Bearer YOUR_ADMIN_TOKEN`

使用

🌐 Usage

MCP 服务器使用可流式的 HTTP 传输协议。任何兼容 MCP 的客户端都可以通过在 Authorization 头中使用 Bearer 令牌并指向 /mcp 端点来进行连接。一旦连接，AI 客户端可以使用自然语言提示与你的 Strapi 内容进行交互。

🌐 The MCP server uses the Streamable HTTP transport protocol. Any MCP-compatible client can connect by pointing to the /mcp endpoint with a Bearer token in the Authorization header. Once connected, the AI client can interact with your Strapi content using natural language prompts.

可用工具

🌐 Available tools

MCP 服务器提供两类工具：由你的架构生成的内容管理工具，以及内置的实用工具。

🌐 The MCP server exposes 2 categories of tools: content management tools generated from your schema, and built-in utility tools.

内容管理工具

🌐 Content management tools

生成的工具取决于内容类型是集合类型还是单一类型。

🌐 The tools generated differ depending on whether the content type is a collection type or a single type.

集合类型 可生成最多 8 个工具：5 个用于 CRUD 操作，3 个用于草稿与发布操作：

工具	操作	所需权限	描述
`list`	读取	`read`	列出条目，支持分页、排序和筛选
`get`	读取	`read`	按文档 ID 获取单个条目
`create`	创建	`create`	创建新条目（如果启用了草稿和发布，则创建为草稿）
`update`	更新	`update`	按文档 ID 更新现有条目
`delete`	删除	`delete`	按文档 ID 删除条目
`publish`	发布	`publish`	发布草稿条目
`unpublish`	取消发布	`publish`	取消发布已发布条目
`discard_draft`	放弃草稿	`publish`	放弃草稿更改并恢复到已发布版本

单一类型 最多生成 6 个工具。由于单一类型总是表示恰好一个文档，因此没有 list 工具，并且创建/更新已合并为单个 write 工具：

工具	操作	所需权限	描述
`get`	读取	`read`	获取单类型文档
`write`	创建或更新	`create` 和/或 `update`	如果不存在文档，则创建文档；否则更新现有草稿
`delete`	删除	`delete`	删除单类型文档
`publish`	发布	`publish`	发布文档
`unpublish`	取消发布	`publish`	取消已发布文档的发布
`discard_draft`	丢弃草稿	`publish`	丢弃草稿更改并恢复到已发布版本

仅当内容类型上启用了 Draft & Publish 时，才会生成发布、取消发布和放弃草稿工具。

🌐 The publish, unpublish, and discard_draft tools are only generated when Draft & Publish is enabled on the content type.

内置实用工具

🌐 Built-in utility tools

除了内容管理工具之外，Strapi 还注册了以下内置工具：

🌐 In addition to content management tools, Strapi registers the following built-in tools:

工具	可用性	描述
`log`	仅开发模式	在指定级别 (`info`, `warn`, `error`, `http`, `log`) 下将消息记录到 Strapi 服务器控制台。对调试 MCP 交互很有用。

内置的实用工具仅在开发模式下可用（当启用 autoReload 时），且不需要特定的管理员权限。

🌐 Built-in utility tools are only available in development mode (when autoReload is enabled) and do not require specific admin permissions.

通过提示进行内容管理

🌐 Content management through prompts

一旦连接，你就可以使用自然语言与你的 Strapi 内容进行交互：

🌐 Once connected, you can interact with your Strapi content using natural language:

提示	会发生什么
"创建一个标题为 'Hello World'、正文为 'First post' 的新文章。"	创建一个草稿文章条目
"列出最近的 5 篇文章。"	返回分页列表，按最新排序
"显示 ID 为 abc123 的文章。"	返回完整条目
"更新文章 abc123，将标题改为 'Hello Strapi'。"	更新标题，其他字段不变
"发布文章 abc123。"	将条目状态更改为已发布
"删除文章 abc123。"	删除该条目
"用法语创建一篇标题为 'Bonjour le monde' 的文章。"	创建一个草稿文章，并将 `locale` 设置为 `fr`

国际化 (i18n)

🌐 Internationalization (i18n)

当在内容类型上启用国际化 (i18n)时，MCP 工具接受一个可选的 locale 参数（例如，"en"、"fr"）。如果省略，则使用默认语言环境。

🌐 When Internationalization (i18n) is enabled on a content type, MCP tools accept an optional locale parameter (e.g., "en", "fr"). If omitted, the default locale is used.

AI 客户端可以查看每个工具架构中可用的语言环境，因此你可以要求它以特定语言创建或更新内容。例如，询问“用法语创建一篇标题为 'Bonjour' 的文章”会将 locale: "fr" 传递给 create 工具。可用的语言环境取决于管理员令牌的权限（请参见权限边界）。

🌐 The AI client sees which locales are available in each tool's schema, so you can ask it to create or update content in a specific language. For example, asking "Create an article in French titled 'Bonjour'" passes locale: "fr" to the create tool. Which locales are available depends on the Admin token's permissions (see Permission boundaries).

Tip

在处理本地化内容时，请在提示中明确提及目标语言，以便 AI 客户端传递正确的 locale 值。例如，建议使用“创建一篇法语文章”，而不是“创建一篇标题为‘Bonjour’的文章”，以避免歧义。

🌐 When working with localized content, explicitly mention the target language in your prompt so the AI client passes the correct locale value. For instance, prefer "Create an article in French" over "Create an article titled 'Bonjour'" to avoid ambiguity.

排序

🌐 Sorting

list 工具接受一个 sort 参数，该参数支持 4 种表示法：

🌐 The list tool accepts a sort parameter that supports 4 notations:

符号	示例
字符串	`"title:asc"`
字符串数组	`["title:asc", "createdAt:desc"]`
对象	`{ "title": "asc" }`
对象数组	`[{ "title": "asc" }, { "createdAt": "desc" }]`

排序字段名称仅限于内容类型的标量属性（字符串、数字、布尔值、日期、枚举）。关系、组件、动态区、媒体和 JSON 字段无法进行排序。

🌐 Sort field names are constrained to the content type's scalar attributes (strings, numbers, booleans, dates, enumerations). Relation, component, dynamic zone, media, and JSON fields cannot be sorted on.

过滤

🌐 Filtering

list 工具使用 Strapi 的过滤语法接受 filters 参数：

🌐 The list tool accepts a filters parameter using Strapi's filter syntax:

字段运算符：$eq、$ne、$in、$notIn、$lt、$lte、$gt、$gte、$between、$contains、$notContains、$startsWith、$endsWith、$null、$notNull，以及它们的不区分大小写变体（$eqi、$nei、$containsi、$notContainsi、$startsWithi、$endsWithi）。
逻辑运算符：$and、$or（接受过滤器对象数组）、$not（封装单个过滤器对象）。
隐式相等：直接传递一个值（例如，{ "title": "Hello" }）等同于 { "title": { "$eq": "Hello" } }。

像排序字段一样，筛选字段也仅限于标量属性。

🌐 Like sort fields, filter fields are constrained to scalar attributes only.

分页

🌐 Pagination

list 工具也接受 page（从 1 开始索引，默认值：1）和 pageSize（默认值：25，最大值：100）参数。

🌐 The list tool also accepts page (1-indexed, default: 1) and pageSize (default: 25, max: 100) parameters.

关系

🌐 Relations

关联字段既支持简写的文档 ID 字符串，也支持完整的关联对象。

🌐 Relation fields support both a shorthand document ID string and a full relation object.

一对一关系 (oneToOne, manyToOne) 接受：

一个文档 ID 字符串："z7v8zma53x01r6oceimv922b"
一个关系对象：{ "documentId": "z7v8zma53x01r6oceimv922b", "locale": "en", "status": "draft" }（locale 和 status 可选）
null 清除关系

多对多关系 (oneToMany, manyToMany) 接受一个包含以下一个或多个键的关系对象：

键	描述
`connect`	添加关系。接受文档 ID 字符串数组或 `{ documentId, locale?, status?, position? }` 对象。可选的 `position` 键支持 `{ before?, after?, start?, end? }` 排序提示（默认: `{ end: true }`）。
`disconnect`	移除关系。接受文档 ID 字符串数组或 `{ documentId, locale?, status? }` 对象。
`set`	使用提供的数组替换所有现有关系。传递 `null` 可清除所有关系。与 `connect`/`disconnect` 互斥。

权限边界

🌐 Permission boundaries

MCP 服务器执行与 Strapi 管理面板相同的权限模型。权限会在多个层级进行检查：

🌐 The MCP server enforces the same permission model as the Strapi admin panel. Permissions are checked at multiple levels:

工具可见性：当 AI 客户端连接时，Strapi 会检查管理员令牌的权限，并且只显示令牌有权限访问的工具。如果令牌未授予在 Article 上的 delete，AI 客户端将完全看不到用于文章的删除工具。
字段过滤：即使在公开的工具中，输入和输出模式也仅限于令牌可以访问的字段。如果令牌在 Article 上授予 read 权限，但排除了 body 字段，则 AI 客户端将无法看到或接收 body 内容。字段限制是针对每个操作独立应用的。写入模式（create、update）仅包括对应操作允许的字段。
区域过滤：当启用国际化 (i18n)功能并配置了区域级权限时，locale参数会根据每个操作进行限制。例如，某个令牌可能允许读取en和fr的内容，但只允许在en中创建内容。如果默认区域被允许用于给定操作，则该区域会作为 Zod 模式的默认值应用，因此 AI 客户端无需显式指定区域。
运行时执行：除了模式级别的限制外，每个处理程序在运行时都会调用 Strapi 的权限检查器，以验证对正在读取、写入或发布的特定文档的访问。基于条件的权限（例如，“仅更新你拥有的条目”）在此级别执行。

这意味着你可以创建具有细粒度访问权限的令牌：

🌐 This means you can create tokens with fine-grained access:

一个只提供列表和读取工具的“只读”令牌
一个限定于特定内容类型的令牌（例如，仅限文章而不包括分类）
一个仅限于特定字段或区域的令牌
具有基于条件权限的令牌（例如，仅更新自己拥有的条目）

Tip

为每个 AI 客户端或用例创建专用的管理员令牌。使用仍然允许 AI 完成其任务的最严格权限。

🌐 Create dedicated Admin tokens for each AI client or use case. Use the most restrictive permissions that still allow the AI to accomplish its task.

无状态架构

🌐 Stateless architecture

MCP 服务器使用无状态架构。每个对 /mcp 端点的 POST 请求都会创建一个新的、短暂的 MCP 服务器实例，该实例的作用范围由已认证令牌的权限决定。请求之间没有会话持久性：每个请求都是独立进行身份验证和授权的。由于没有会话状态，AI 客户端无需管理会话 ID，并且权限更改（例如撤销令牌或更新其权限）会在下一次请求中生效。

🌐 The MCP server uses a stateless architecture. Each POST request to the /mcp endpoint creates a fresh, ephemeral MCP server instance scoped to the authenticated token's permissions. There is no session persistence between requests: every request is independently authenticated and authorized. Because there is no session state, the AI client does not need to manage session IDs, and permission changes (such as revoking a token or updating its permissions) take effect on the next request.

/mcp 端点上的 GET 和 DELETE HTTP 方法会返回 405 Method Not Allowed JSON-RPC 错误，因为 MCP 服务器仅接受 POST 请求。

🌐 GET and DELETE HTTP methods on the /mcp endpoint return a 405 Method Not Allowed JSON-RPC error, as the MCP server only accepts POST requests.

已知限制

🌐 Known limitations

MCP 服务器有以下限制：

🌐 The MCP server has the following limitations:

动态区域：动态区域字段在工具模式中以无类型数组的形式传递。动态区域中每个组件的内部结构未被描述。
嵌套人口参数：list 和 get 工具不支持关系的嵌套人口参数。
媒体上传：媒体字段接受现有的媒体资源引用，但 MCP 服务器无法上传新文件。请先使用 Strapi 的媒体库或上传 API 添加文件，然后在 MCP 工具调用中引用它们。
自定义字段：通过插件注册的自定义字段会映射到其底层的 Strapi 类型。如果在注册 MCP 工具时自定义字段注册表未被填充，该自定义字段将回退到 unknown 类型。
循环组件引用：直接或间接引用自身的组件，在循环点将回退到一个开放的 record<string, unknown> 模式，而不是形成无限递归结构。

插件 API

🌐 Plugin API

Strapi 插件可以通过 strapi.ai.mcp 服务注册额外的 MCP 工具，因此 AI 客户端可以触发特定插件的操作。点击下面的卡片以阅读更多详情：

🌐 Strapi plugins can register additional MCP tools through the strapi.ai.mcp service, so AI clients can trigger plugin-specific actions. Click on the card below to read more details:

扩展 MCP 服务器

通过 strapi.ai.mcp 服务从 Strapi 插件注册自定义 MCP 工具。

配置​

基于代码的 Strapi 配置​

高级选项​

Strapi 管理面板配置​

AI客户端配置​

连接 Claude 桌面​

连接Claude代码​

连接光标​

连接帆板​

连接其他MCP客户端​

使用​

可用工具​

内容管理工具​

内置实用工具​

通过提示进行内容管理​

国际化 (i18n)​

排序​

过滤​

分页​

关系​

权限边界​

无状态架构​

已知限制​

插件 API​