如何将 Claude Code 通过 MCP 连接到你的 CMS

Claude Code 可以编写你的应用，但无法看到你的内容。Cosmic MCP 服务器通过 18 个用于对象、媒体、模式和 AI 生成的工具弥合了这一差距。

Dev.to · Jul 30, 2026

How to Connect Claude Code to Your CMS with MCP

Claude Code 对你的代码仓库了如指掌，却对你的内容一无所知。它可以重构渲染博客的组件，但当你让它发布该组件所展示的文章时，它却无处可查。模型上下文协议（MCP）弥合了这一差距。它为 Claude Code 提供了一套可以直接针对你的 CMS 调用的工具，因此内容的读取和写入与代码编写在同一对话中完成。

本指南将 Claude Code 连接到 Cosmic 存储桶。使用托管端点只需大约五分钟，无需安装。

MCP 究竟为 Claude Code 提供了什么

MCP 是一个用于向 AI 助手公开工具的开放协议。Cosmic MCP 服务器实现了该协议，并提供了 18 个工具，涵盖四个领域：

对象（5 个工具）：列出、获取、创建、更新和删除内容
媒体（4 个工具）：列出、获取、上传和删除文件
对象类型（5 个工具）：列出、获取、创建、更新和删除内容模型
AI 生成（4 个工具）：将文本、图像、视频和音频生成为你的存储桶内容

连接后，“发布 MCP 草稿并为其生成一张主图”即可转化为对你的存储桶的真实工具调用。无需浏览器标签页，无需复制粘贴，也无需手动导出。

有两种连接方式：

托管 MCP（推荐）：将你的客户端指向 https://mcp.cosmicjs.com/v1/buckets/{your-bucket-slug}，并使用你的存储桶密钥进行身份验证。无需安装任何内容。
自托管（stdio）：通过 npx 在本地运行 @cosmicjs/mcp npm 包。适用于离线工作，或希望 MCP 进程在你自己的开发环境中运行时使用。

开始之前

你需要三样东西：

一个 Cosmic 存储桶。免费套餐每月 0 美元，包括 1 个存储桶、2 名团队成员和 1,000 个对象，足以跟进本指南。免费开始。
你的存储桶 slug、读取密钥和写入密钥。第 1 步将介绍如何找到它们。
已安装 Claude Code。

托管方式完全不需要本地运行时。只有在选择通过 npx 运行的自托管 stdio 选项时才需要 Node。

第 1 步：获取你的存储桶凭证

登录 Cosmic 仪表盘
导航到你的存储桶
进入设置 -> API 访问
复制你的 存储桶 slug、读取密钥 和 写入密钥

在粘贴任何内容之前有一个建议：先从读取密钥开始。Cosmic 为每个存储桶分别颁发读取和写入密钥，因此你可以让 Claude Code 完全可见你的内容，同时使其在结构上无法更改内容。一旦你信任设置，再添加写入密钥。下文的“只读与完全访问”部分将详细说明具体变化。

第 2 步：使用托管 MCP 连接（推荐）

Claude Code 会从仓库根目录的 .mcp.json 文件中拾取项目范围的 MCP 服务器。创建方式如下：

{
  "mcpServers": {
    "cosmic": {
      "url": "https://mcp.cosmicjs.com/v1/buckets/your-bucket-slug",
      "headers": {
        "Authorization": "Bearer your-read-key:your-write-key"
      }
    }
  }
}

进入全屏模式退出全屏模式

将 your-bucket-slug、your-read-key 和 your-write-key 替换为第 1 步中获取的值。该端点支持 streamable-HTTP MCP 传输。

授权标头的工作原理

Cosmic 将两个密钥打包成一个 bearer token，用冒号分隔。写入密钥位于冒号之后：

# 只读访问
Authorization: Bearer rk_abc123def456

# 完全访问（读取 + 写入）
Authorization: Bearer rk_abc123def456:wk_zyx987wvu654

进入全屏模式退出全屏模式

如果要只读访问，请省略冒号和写入密钥。如果你的客户端无法发送冒号分隔的令牌，你可以使用 X-Cosmic-Write-Key 标头带外传递写入密钥。

一个注意事项： .mcp.json 现已包含实时凭证，因此请在下次提交前将其添加到 .gitignore 中。

相同的 mcpServers 块也适用于 Claude Desktop 和 Cursor。MCP 服务器文档列出了每个客户端的确切配置文件路径，包括 macOS 上的 ~/Library/Application Support/Claude/claude_desktop_config.json 和 Cursor 的 .cursor/mcp.json。

第 2 步，替代方案：通过 stdio 自托管

如果你更愿意自己运行服务器，@cosmicjs/mcp 包提供了一个 stdio 二进制文件。将 Claude Code 指向 npx：

{
  "mcpServers": {
    "cosmic": {
      "command": "npx",
      "args": ["@cosmicjs/mcp"],
      "env": {
        "COSMIC_BUCKET_SLUG": "your-bucket-slug",
        "COSMIC_READ_KEY": "your-read-key",
        "COSMIC_WRITE_KEY": "your-write-key"
      }
    }
  }
}

进入全屏模式退出全屏模式

stdio 二进制文件从环境变量中读取凭证：

COSMIC_BUCKET_SLUG（必需）：你的 Cosmic 存储桶 slug
COSMIC_READ_KEY（必需）：存储桶读取密钥，用于读取操作
COSMIC_WRITE_KEY（可选）：存储桶写入密钥，用于写入操作

如果要只读服务器，请完全省略 COSMIC_WRITE_KEY。你也可以使用 npm install -g @cosmicjs/mcp 全局安装，而不是每次都通过 npx 解析。

第 3 步：验证连接

重启 Claude Code 并运行：

/mcp

进入全屏模式退出全屏模式

你应该看到 cosmic 及其工具列出。然后，通过询问只有你的存储桶才知道的内容来确认它确实可以访问你的存储桶：

列出我 Cosmic 存储桶中的所有对象类型

进入全屏模式退出全屏模式

Claude Code 应该调用 cosmic_types_list 并返回你真实的内容模型。如果它返回你的对象类型，则连接已生效且身份验证正确。

18 个工具及其触发时机

对象

cosmic_objects_list：列出或搜索对象，可按类型、状态和区域设置筛选，支持分页
cosmic_objects_get：通过 ID 或 slug 获取单个对象，支持可选的元字段、深度和区域设置参数
cosmic_objects_create：使用标题、slug、状态和元字段创建新对象（需要写入密钥）
cosmic_objects_update：更新现有对象的标题、slug、状态或元字段值（需要写入密钥）
cosmic_objects_delete：按 ID 永久删除对象（需要写入密钥）

媒体

cosmic_media_list：列出媒体文件，可选择按文件夹范围
cosmic_media_get：获取单个文件的元数据和 imgix URL
cosmic_media_upload：将 URL 或 base64 负载上传到媒体库（需要写入密钥）
cosmic_media_delete：删除媒体文件（需要写入密钥）

对象类型

cosmic_types_list：列出存储桶中的所有对象类型
cosmic_types_get：获取单个对象类型的完整模式，包括元字段、选项和帮助文本
cosmic_types_create：使用元字段模式创建新对象类型（需要写入密钥）
cosmic_types_update：更新类型的模式或元字段定义（需要写入密钥）
cosmic_types_delete：删除对象类型及其所有对象（需要写入密钥）

AI 生成

cosmic_ai_generate_text：生成文本，可选地从存储桶中的现有对象中提取上下文
cosmic_ai_generate_image：生成图像并将其存储在媒体库中（需要写入密钥）
cosmic_ai_generate_video：使用 Google Veo 生成视频并存储在媒体库中（需要写入密钥）
cosmic_ai_generate_audio：使用 OpenAI TTS 生成旁白，提供 13 种语音，并存储在媒体库中（需要写入密钥）

值得为代理工作调用的两个工具是 cosmic_types_list 和 cosmic_types_get。一个在写入前读取你模式的代理，会在第一次尝试时就生成有效的元字段，而不是猜测键名并失败。

只读与完全访问

在将代理指向生产存储桶之前，这部分内容非常重要。

使用只读令牌时，每个写入工具都会被阻止并显示明确的错误消息，而读取工具则正常工作。具体来说，被阻止的工具包括所有 *_create、*_update 和 *_delete 工具，以及所有四个 AI 生成工具，因为这些工具都会将生成的资产写入你的媒体库。

因此，只读设置仍允许 Claude Code 探索你的内容模型、读取每个对象，并在编写应用程序代码时对你的内容进行推理。它只是无法修改任何内容。这是对真实数据进行首次会话时的良好默认设置。

实际操作示例

服务器连接后，以下所有操作均为单个提示：

列出我 Cosmic 存储桶中的所有博客文章

进入全屏模式退出全屏模式

创建一个新的博客文章，标题为“开始使用 MCP”，内容为
“这是对模型上下文协议的介绍……”

进入全屏模式退出全屏模式

将 ID 为 “abc123” 的博客文章状态更新为已发布

进入全屏模式退出全屏模式

显示 “blog-images” 文件夹中的所有图像

进入全屏模式退出全屏模式

创建一个名为 “Products” 的新对象类型，包含名称、价格、
描述和图像字段

进入全屏模式退出全屏模式

使用 “nova” 语音生成 “Welcome to Cosmic CMS” 的音频旁白，
并将其上传到我的媒体库

进入全屏模式退出全屏模式

模式管理用例是开发者往往低估的。内容建模通常是一项仪表盘任务。通过 MCP，它可以在你搭建将要使用它的组件的同一提示中完成。

代理范围：当用户尚无 Cosmic 帐户时

托管端点在 https://mcp.cosmicjs.com/v1/agent 处公开了第二个较小的范围，用于代理注册流程。它允许 AI 代理代表没有帐户的人配置一个全新的 Cosmic 项目和存储桶，而无需离开 MCP 传输。它公开了三个工具：

cosmic_agent_signup（无需身份验证）：创建一个与 human_email 绑定的未认领项目和存储桶。返回 agent_key、read_key、write_key 和 claim_url。Cosmic 会向用户发送一个 6 位数的 OTP。
cosmic_agent_verify（需要 agent_key）：提交 OTP，解除受限模式限制，并启用 AI 生成。
cosmic_agent_status（需要 agent_key）：检查认领状态、剩余限制并恢复存储桶密钥。

新存储桶以受限模式启动：无 AI 额度，最大 50 个对象，以及 5 MB 媒体上限。未认领的项目将在 14 天后被硬删除。

上面列出的存储桶范围工具在代理端点上不可用，代理工具在存储桶端点上也不可用。一次对话通常会同时使用两者：代理为用户注册，捕获返回的存储桶密钥，然后切换到存储桶范围开始创建内容。

MCP 服务器与 Agent Skills

Cosmic 提供了两项听起来相似但功能不同的事物：

MCP 服务器用于直接内容管理。它回答“列出我的博客文章”。AI 调用在你的存储桶上操作的工具。
Agent Skills用于代码生成指导。它回答“使用 Cosmic 构建一个博客”。AI 使用 SDK 编写应用程序代码。

两者都可使用。Agent Skills 帮助 Claude Code 编写如下代码：

import { createBucketClient } from '@cosmicjs/sdk';

const cosmic = createBucketClient({
  bucketSlug: 'your-bucket-slug',
  readKey: 'your-read-key',
});

const { objects: posts } = await cosmic.objects
  .find({ type: 'blog-posts' })
  .props(['title', 'slug', 'metadata'])
  .depth(1);

进入全屏模式退出全屏模式

然后，MCP 服务器允许同一会话管理该代码渲染的内容。一个工具编写应用，另一个操作其背后的数据。

生产存储桶的防护措施

值得养成的四个习惯：

先使用读取密钥。前几次会话使用只读令牌进行连接。在你看到代理实际操作后，再添加写入密钥。
在单独的存储桶中进行实验。存储桶额度随你的套餐而增加：免费套餐包括 1 个，Builder（49 美元/月）包括 2 个，Team（299 美元/月）包括 3 个，Business（499 美元/月）包括 5 个。将破坏性实验指向一个你不介意丢失的存储桶。
将删除工具视为仅手动批准。cosmic_objects_delete、cosmic_media_delete，尤其是 cosmic_types_delete 是永久性的，删除对象类型会将其所有对象一并删除。切勿让代理推测性地调用这些工具。
注意席位。套餐包括一定数量的团队成员（免费 2 名，Builder 3 名，Team 5 名，Business 10 名），额外的用户为 29 美元/用户/月，因此请决定谁需要仪表盘访问权限，而不是默认添加所有人。

故障排除

服务器未出现在 /mcp 中。确认 .mcp.json 是仓库根目录的有效 JSON，然后重启 Claude Code。某些 Claude Code 版本需要明确命名传输，因此如果托管配置仍无法连接，请尝试在 url 旁边添加 "type": "http"。

npx 找不到该包。包名是 @cosmicjs/mcp，是带作用域的，包含 @。请确认 Node 已安装并在你的 PATH 中。

写入工具返回错误，但读取工具正常工作。你的 bearer token 缺少写入密钥。请检查标头是否为 Bearer READ_KEY:WRITE_KEY（带冒号且无空格），或通过 X-Cosmic-Write-Key 发送写入密钥。

托管端点返回 404。URL 中的存储桶 slug 错误。请从设置 -> API 访问 重新复制，因为 slug 并不总是与你项目的显示名称相同。

工具已连接但未返回任何内容。确认你指向的是你认为的存储桶。让 Claude Code 运行 cosmic_types_list，并将结果与仪表盘进行比较。

后续步骤

从托管端点和只读令牌开始。让 Claude Code 列出你的对象类型，然后让它总结你存储桶中的内容。一旦成功，添加写入密钥并让它起草一些内容。完整的工具参考和每个客户端的配置路径，请参阅 MCP 服务器文档。

亲自体验。Cosmic 是一个 AI 驱动的无头 CMS，拥有 REST API、TypeScript SDK 和托管 MCP 服务器。创建免费帐户，在约五分钟内连接 Claude Code。正在为团队评估 Cosmic？与 Tony 预约通话。

最初发布于 Cosmic 博客。

Read the original source Next news

#Ai #Backend

如何将 Claude Code 通过 MCP 连接到你的 CMS

MCP 究竟为 Claude Code 提供了什么

开始之前

第 1 步：获取你的存储桶凭证

第 2 步：使用托管 MCP 连接（推荐）

授权标头的工作原理

第 2 步，替代方案：通过 stdio 自托管

第 3 步：验证连接

18 个工具及其触发时机

对象

媒体

对象类型

AI 生成

只读与完全访问

实际操作示例

代理范围：当用户尚无 Cosmic 帐户时

MCP 服务器与 Agent Skills

生产存储桶的防护措施

故障排除

后续步骤

0 Comments