Elmapicms Mcp Server

ElmapiCMS MCP 服务

这是一个 MCP（Model Context Protocol）服务，可将 Cursor 和 Claude Code 等 AI Agent 连接到你的 ElmapiCMS 实例。通过自然语言以编程方式管理集合、字段、内容条目、资源和 Webhook。

配置

变量	描述
ELMAPI_BASE_URL	实例 API 根地址（例如，https://your-domain.com/api）。也接受 ELMAPI_API_URL 作为别名。
ELMAPI_API_KEY	来自 Project settings → API Tokens 的 Project Sanctum 令牌
ELMAPI_PROJECT_ID	项目 UUID，可在项目主页或 Project settings → API Access 中找到

在 Cursor 中使用

将以下内容添加到 Cursor MCP 设置（~/.cursor/mcp.json）：

{
  "mcpServers": {
    "elmapicms": {
      "command": "npx",
      "args": ["-y", "@elmapicms/mcp-server"],
      "env": {
        "ELMAPI_BASE_URL": "https://your-domain.com/api",
        "ELMAPI_API_KEY": "your-project-api-token",
        "ELMAPI_PROJECT_ID": "your-project-uuid"
      }
    }
  }
}

在 Claude Code 中使用

claude mcp add elmapicms \
  -e ELMAPI_BASE_URL=https://your-domain.com/api \
  -e ELMAPI_API_KEY=your-project-api-token \
  -e ELMAPI_PROJECT_ID=your-project-uuid \
  -- npx -y @elmapicms/mcp-server

本地开发（Laravel Herd / .test 域名）

如果你的实例使用自签名证书（例如，Laravel Herd），你可能需要：

"env": {
  "ELMAPI_BASE_URL": "https://myproject.test/api",
  "ELMAPI_API_KEY": "your-project-api-token",
  "ELMAPI_PROJECT_ID": "your-project-uuid",
  "NODE_TLS_REJECT_UNAUTHORIZED": "0"
}

建议修复本地 CA 信任问题（例如，使用 node --use-system-ca），而不是在生产配置中禁用 TLS 验证。

可用工具（40）

项目

• get_project — 获取项目信息（default_locale、locales 等）
• add_project_locale — 向项目添加区域设置代码（需要 admin 权限）
• set_default_project_locale — 设置默认区域设置（需要 admin 权限）

这里有意不提供移除区域设置的功能（请在仪表板中使用 Project settings → Localization，或使用 REST/SDK API）。

集合

• list_collections — 列出所有集合
• get_collection — 获取集合及其完整字段架构
• create_collection — 创建集合（可选：批量创建字段）
• update_collection — 更新集合名称和 slug
• reorder_collections — 重新排列集合

字段

• create_field — 向集合添加字段
• update_field — 更新字段
• reorder_fields — 在集合中重新排列字段

内容条目

• list_entries — 使用高级筛选条件（where 支持 13 种运算符、OR 组、关系筛选）、排序、分页、数量统计和首条结果列出条目
• get_entry — 获取单个内容条目
• create_entry — 创建内容条目
• update_entry — 更新内容条目
• patch_entry — 部分更新条目（HTTP PATCH；仅合并发送的字段）
• publish_entry — 将草稿发布为新的不可变版本（update）
• unpublish_entry — 清除当前已发布版本的指针；保留版本（update）
• discard_entry_draft — 丢弃未发布的草稿更改（update）
• delete_entry — 软删除内容条目（移至回收站）
• bulk_create_entries — 原子性地创建多个条目
• bulk_update_entries — 按 UUID 原子性地更新多个条目
• bulk_delete_entries — 按 UUID 原子性地删除多个条目
• link_entry_translation — 将两个条目（不同语言区域）关联到同一翻译组（POST …/link-translation；需要 update）
• list_entry_versions — 列出条目的版本历史
• get_entry_version — 按版本号获取一个版本（包含快照内容）
• revert_entry_version — 从先前的快照恢复草稿并发布（update）
• update_entry_version_label — 编辑版本的标签/说明；快照保持不变（update）

内容 API 结构： 每个条目都有 uuid、locale、published_at 和 fields（自定义字段值）。字段名称采用 kebab-case。富文本写入格式遵循 editor.mode：对于 lexical，使用 HTML 字符串或 { html, json }；当 mode 为 markdown 时，使用 markdown 字符串。MCP create_field / create_collection（以及富文本 update_field）会将未指定的 editor.mode 默认为 markdown。使用 Lexical 时传入 mode: 'lexical'。绝不要将 markdown 写入 lexical 字段。读取格式遵循 editor.outputFormat。读取关系字段时会返回嵌套条目对象（一对多关系则返回数组）；写入时只发送相关条目的 UUID 或数字 id（绝不要发送先前 get_entry 返回的完整嵌套对象）。get_entry 支持 translation_locale、exclude、timestamps 和 state 查询参数。

保存 ≠ 发布： create_entry / update_entry / patch_entry 只保存草稿。state=published 的列表/获取操作会继续返回最近一次快照，直到调用 publish_entry。

资源 URL： API 会将 url、thumbnail_url 和 original_url 作为稳定链接返回（可选 ?variant=thumbnail 或 ?variant=original）。

资源文件

• list_assets — 分页列出资源文件
• get_asset — 按 UUID 或文件名获取资源文件
• upload_asset — 将文件上传为资源文件
• bulk_upload_assets — 原子性地上传多个文件
• bulk_update_asset_metadata — 原子性地更新多个资源文件的元数据
• delete_asset — 删除资源文件

Webhook

• list_webhooks — 列出项目的所有 webhook
• get_webhook — 按 UUID 获取 webhook
• create_webhook — 为内容和身份验证事件创建 webhook（name、url、events、sources；可选 description、secret、payload、status、collection_ids）
• update_webhook — 按 UUID 更新 webhook（字段与创建时相同）
• delete_webhook — 按 UUID 删除 webhook
• list_webhook_logs — 列出 webhook 的投递日志（uuid；可选 paginate、page）

资源

服务会公开三个参考资源，供 AI Agent 阅读并了解相关信息：

• 字段类型参考（elmapicms://field-types）— 完整介绍全部 16 种字段类型、其选项、验证规则和常见用法。
• 集合指南（elmapicms://collections-guide）— 介绍如何使用集合、单例、保留 slug 及最佳实践。
• 查询参考（elmapicms://query-reference）— 内容查询的完整文档：包含 13 种运算符的 where 筛选条件、OR 组、关系筛选、排序、分页和示例。

API 令牌权限

你的项目 API 令牌需要具备相应权限，才能使用所需的工具：

权限	工具
read	列出/获取集合、条目、资源、webhook；查看 webhook 日志
create	创建条目、上传资源、创建 webhook
update	更新条目、发布/取消发布/丢弃草稿、link_entry_translation、版本、更新资源元数据、更新 webhook
delete	删除条目、删除资源、删除 webhook
admin	创建/更新/重新排序集合和字段；添加/设置默认项目语言区域（MCP 不提供移除语言区域的功能）

在 ElmapiCMS 控制面板中，通过项目设置 → API 令牌创建令牌。配置此服务时，可从项目主页或项目设置 → API 访问复制项目 ID。

使用多个项目

每个 MCP 条目都连接到一个 ElmapiCMS 项目。要使用多个项目，请在 MCP 配置中添加单独的条目，并设置不同的环境变量值。

许可证

MIT