Nomacms Mcp Server

NomaCMS MCP 服务

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

配置

• NOMA_API_KEY：用户设置 → API 密钥中的 API 密钥——参见 API 密钥权限。
• NOMA_PROJECT_ID：项目的 UUID——可在项目主页或 项目设置 → API 访问中找到。

在 Cursor 中使用

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

{
  "mcpServers": {
    "nomacms": {
      "command": "npx",
      "args": ["-y", "@nomacms/mcp-server"],
      "env": {
        "NOMA_API_KEY": "your-api-key",
        "NOMA_PROJECT_ID": "your-project-uuid"
      }
    }
  }
}

在 Claude Code 中使用

使用 Claude Code CLI 添加 MCP 服务：

claude mcp add nomacms \
  -e NOMA_API_KEY=your-api-key \
  -e NOMA_PROJECT_ID=your-project-uuid \
  -- npx -y @nomacms/mcp-server

可用工具（39）

项目

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

此处有意不提供移除语言区域的功能（如需移除语言区域，请在 NomaCMS 控制面板中使用 项目设置 → 本地化）。

集合

• 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）
• 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（自定义字段值）。写入时，富文本值为 Markdown 字符串；读取时则根据字段的 editor.outputFormat（markdown 或 html）返回原始 Markdown 或渲染后的 HTML。读取时，关系字段会返回嵌套条目对象（一对多关系则返回数组）；写入时，仅发送关联条目的 UUID 或 数字 id（切勿发送先前 get_entry 返回的完整嵌套对象）。get_entry 支持 translation_locale、exclude、timestamps 和 state 查询参数。

资源 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 阅读以获取背景信息：

• 字段类型参考（nomacms://field-types）— 16 种字段类型的完整参考，包含其选项、验证规则和常见模式。
• 集合指南（nomacms://collections-guide）— 关于集合、单例、保留 slug 和最佳实践的指南。
• 查询参考（nomacms://query-reference）— 内容查询的完整文档：包含 13 种运算符的 where 过滤器、OR 分组、关联过滤、排序、分页和示例。

API 密钥权限

你的 API 密钥需要具备相应权限，才能使用所需工具：

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

在 NomaCMS 控制面板的用户设置 → API 密钥下创建密钥。配置此服务器时，从项目主页或项目设置 → API 访问中复制项目 ID。

使用多个项目

每个 MCP 配置项仅连接到一个 NomaCMS 项目。要使用多个项目，请在 MCP 配置中添加单独的配置项：

{
  "mcpServers": {
    "nomacms-blog": {
      "command": "npx",
      "args": ["-y", "@nomacms/mcp-server"],
      "env": {
        "NOMA_API_KEY": "blog-project-api-key",
        "NOMA_PROJECT_ID": "blog-project-uuid"
      }
    },
    "nomacms-store": {
      "command": "npx",
      "args": ["-y", "@nomacms/mcp-server"],
      "env": {
        "NOMA_API_KEY": "store-project-api-key",
        "NOMA_PROJECT_ID": "store-project-uuid"
      }
    }
  }
}

许可证

MIT