Cosmic

Cosmic MCP 服务

Cosmic 是一款无头 CMS，提供托管的 MCP 服务、产品内 AI 工作流和 Agent 注册功能。Agent 可以读取和写入内容、在媒体库中生成文本、图像、视频和音频、串联内容、代码和浏览器步骤，也可以在没有现有账户的情况下创建新项目。

功能表：https://www.cosmicjs.com/ai-cms

注册 MCP（无需凭据）：https://mcp.cosmicjs.com/v1/agent

功能

• 内容管理：在 Cosmic 存储桶中创建、读取、更新和删除对象
• 媒体管理：上传、列出和管理媒体文件
• 架构管理：使用自定义元字段创建和修改对象类型
• AI 生成：使用 Cosmic 的 AI 功能生成文本、图像和视频

托管端点（推荐）

Cosmic 运营着一个托管的流式 HTTP MCP 服务。无需安装。

URL：https://mcp.cosmicjs.com/v1/buckets/{bucket-slug}

Cosmic 为每个存储桶分别使用读密钥和写密钥。使用以下任一方式进行身份验证：

Authorization: Bearer <read_key>                       # read-only tools
Authorization: Bearer <read_key>:<write_key>           # full access

如果客户端无法将令牌按冒号组合，也可以通过 X-Cosmic-Write-Key 标头在带外发送写密钥。密钥可在 Cosmic 控制面板中存储桶的 API Access 设置里获取。

只读访问（列出/获取工具）请使用读密钥；完整访问（包括创建对象、上传媒体和 AI 生成）请使用写密钥。

Claude Desktop（远程 MCP）

在 Claude Desktop 中，选择 Settings -> Connectors -> Add custom connector，然后输入：

• URL：https://mcp.cosmicjs.com/v1/buckets/your-bucket-slug
• Bearer token：只读访问使用 <read_key>，完整访问使用 <read_key>:<write_key>

Cursor（远程 MCP）

添加到 .cursor/mcp.json：

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

本地安装（stdio）

对于不支持远程 MCP 的环境，同一服务可通过 stdio 在本地运行。

使用 npx（推荐）

npx @cosmicjs/mcp

全局安装

npm install -g @cosmicjs/mcp
cosmic-mcp

从源代码安装

git clone https://github.com/cosmicjs/mcp.git
cd mcp
bun install
bun run build

配置

此服务需要以下环境变量：

变量	必需	描述
COSMIC_BUCKET_SLUG	是	你的 Cosmic 存储桶 slug
COSMIC_READ_KEY	是	用于读取操作的存储桶读密钥
COSMIC_WRITE_KEY	否	用于写入操作的存储桶写密钥

获取凭据

1. 登录你的 Cosmic 控制面板
2. 前往你的存储桶
3. 转到 Settings → API Access
4. 复制存储桶 slug、读密钥和写密钥

在 Claude Desktop 中通过本地 stdio 运行

如果你更愿意在本地运行 MCP 服务，而不是使用托管端点，请将以下内容添加到 Claude Desktop 配置文件中。

macOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "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"
      }
    }
  }
}

在 Cursor 中通过本地 stdio 运行

{
  "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"
      }
    }
  }
}

可用工具

对象

工具	描述
cosmic_objects_list	列出对象，可按类型、状态筛选并分页
cosmic_objects_get	按 ID 或 slug 获取单个对象
cosmic_objects_create	创建新对象（需要写密钥）
cosmic_objects_update	更新现有对象（需要写密钥）
cosmic_objects_delete	删除对象（需要写密钥）

媒体

工具	描述
cosmic_media_list	列出媒体文件，可按文件夹筛选
cosmic_media_get	按 ID 获取媒体详情
cosmic_media_upload	从 URL 或 base64 上传媒体（需要写密钥）
cosmic_media_delete	删除媒体文件（需要写密钥）

对象类型

工具	描述
cosmic_types_list	列出存储桶中的所有对象类型
cosmic_types_get	按 slug 获取对象类型架构
cosmic_types_create	创建新的对象类型（需要写入密钥）
cosmic_types_update	更新对象类型架构（需要写入密钥）
cosmic_types_delete	删除对象类型（需要写入密钥）

AI 生成

工具	描述
cosmic_ai_generate_text	使用 AI 生成文本内容
cosmic_ai_generate_image	生成并上传 AI 图像或 SVG（需要写入密钥）
cosmic_ai_generate_video	生成并上传 AI 视频（需要写入密钥）

内容块

工具	描述
cosmic_blocks_list	列出存储桶中可重复使用的富文本内容块（即富文本字段中可用的 {{name /}} 标记）

示例提示词

以下是一些可与 Claude 或 Cursor 搭配使用的示例提示词：

内容管理

List all blog posts in my Cosmic bucket

Create a new blog post titled "Getting Started with MCP" with the content "This is an introduction to the Model Context Protocol..."

Update the blog post with ID "abc123" to change its status to published

媒体

Show me all images in the "blog-images" folder

Upload this image URL to my media library: https://example.com/image.jpg

架构管理

Show me all object types in my bucket

Create a new object type called "Products" with fields for name, price, description, and image

AI 生成

Generate a product description for a wireless bluetooth headphone

Generate an image of a futuristic city skyline at sunset and upload it to my media library

开发

构建

bun run build

这会生成两个二进制文件：

• dist/stdio.js - 通过 npm 发布的 stdio 入口（bin: cosmic-mcp）
• dist/http.js - 托管的可流式传输 HTTP 入口（部署到 ECS Fargate）

监视模式（stdio）

bun run dev

本地运行（stdio）

COSMIC_BUCKET_SLUG=your-bucket \
COSMIC_READ_KEY=your-read-key \
COSMIC_WRITE_KEY=your-write-key \
bun run start

本地运行（HTTP）

bun run dev:http
# Server listens on http://localhost:3000
# POST http://localhost:3000/v1/buckets/{slug} with Authorization: Bearer <key>

部署

推送到 main 后，会通过 GitHub Actions 部署到 https://mcp.cosmicjs.com。工作流： .github/workflows/deploy.yml。

发布到 npm

发布使用与 @cosmicjs/sdk 相同的 Changesets 流程。每项需要发布的更改都要添加一个 changeset（bunx changeset），说明版本升级幅度（patch | minor | major）。不要手动编辑 package.json 中的 version 字段。

1. 将功能 PR 合并到 main。必须通过 Package Checks。
2. CI 会新建或更新 Version Packages PR。该 PR 会应用 changeset、升级版本、更新 CHANGELOG.md，并运行 scripts/sync-version.mjs，以确保 server.json 和 SERVER_VERSION 保持同步。
3. 合并 Version Packages PR 后，会通过 publish.yml 发布到 npm（需要仓库密钥 NPM_TOKEN）。

不要手动推送 v*.*.* 标签。托管的 MCP 服务会通过 deploy.yml 从 main / staging 单独部署。

发布到 MCP 注册表

该服务列在 registry.modelcontextprotocol.io 的 com.cosmicjs 命名空间下，其信息由 server.json 描述。

发布顺序很重要：注册表会根据 npm 上的实际内容验证条目，因此应先发布到 npm，再发布条目。package.json 中的 mcpName 必须始终与 server.json 中的 name 相同，注册表会据此验证我们拥有该 npm 包。

证明域名所有权的一次性设置。这里使用 ECDSA P-384，因为 macOS 自带的 LibreSSL 无法生成 Ed25519 密钥（如果更倾向于使用 Ed25519，可运行 brew install openssl@3）：

openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:secp384r1 -out key.pem

PUBLIC_KEY="$(openssl ec -in key.pem -text -noout -conv_form compressed | grep -A4 "pub:" | tail -n +2 | tr -d ' :\n' | xxd -r -p | base64)"
echo "cosmicjs.com. IN TXT \"v=MCPv1; k=ecdsap384; p=${PUBLIC_KEY}\""

将该 TXT 记录添加到 cosmicjs.com 的根域名。选择器（例如 _mcp-auth.cosmicjs.com）不会被找到，并会导致通用签名错误。根域名的 TXT 记录集还包含 SPF 和 Google 验证记录，因此请在其中追加，而不要替换它。不要将 key.pem 放入仓库；它应保存在 ~/.cosmic-mcp/key.pem。

之后，每次发布 npm 后，都要发布条目（先运行 brew install mcp-publisher）：

PRIVATE_KEY="$(openssl ec -in ~/.cosmic-mcp/key.pem -noout -text | grep -A4 "priv:" | tail -n +2 | tr -d ' :\n')"
mcp-publisher login dns --algorithm ecdsap384 --domain cosmicjs.com --private-key "${PRIVATE_KEY}"
mcp-publisher publish

必须使用 --algorithm ecdsap384。发布工具默认使用 ed25519，并会拒绝 P-384 密钥，提示 invalid seed length: expected 32 bytes, got 48；这个错误看起来像是密钥损坏，而不是算法错误。

API 参考

有关 Cosmic API 的更多信息，请参阅：

• Cosmic 文档
• API 参考
• JavaScript SDK

许可证

MIT

参与贡献

欢迎贡献！请创建 issue 或提交 pull request。

支持

• Cosmic 文档
• Cosmic Discord
• GitHub Issues