Cosmic — Claude Code MCP server: what it does, how to install
Connects AI assistants to the Cosmic headless CMS to query content, update schema types, and upload media directly from editor chats.
claude mcp add mcp -e COSMIC_BUCKET_SLUG=<COSMIC_BUCKET_SLUG> -e COSMIC_READ_KEY=<COSMIC_READ_KEY> -e COSMIC_WRITE_KEY=<COSMIC_WRITE_KEY> -- npx -y @cosmicjs/mcpWhat Cosmic does
This server bridges AI agents with Cosmic CMS buckets. It exposes tools to inspect and mutate content objects, fetch schema definitions, and configure metadata fields. The server also handles media operations, allowing assistants to upload files directly or trigger Cosmic AI text and video generation.
Cosmic offers a hosted HTTP endpoint at https://mcp.cosmicjs.com/v1/buckets/{bucket-slug}, avoiding local dependency installations. Teams working without remote server support can run the package locally via npx -y @cosmicjs/mcp. Local execution requires setting COSMIC_BUCKET_SLUG alongside access keys.
Read access and write operations rely on distinct credentials. Supplying only COSMIC_READ_KEY blocks all mutations. To modify records, alter schema types, or publish generated assets, you must provide COSMIC_WRITE_KEY.
What it helps with
- update and delete entries inside Cosmic content buckets
- upload images and assets directly into the media library
- define object types with custom metafield structures
- trigger media generation through Cosmic AI utilities
Example prompts for the agent
- List all blog post objects currently stored in the Cosmic bucket.
- Create a new object type named Products with price and description fields.
- Upload this image URL into the blog media folder.
How to install Cosmic
1Platform CLI
claude mcp add mcp -e COSMIC_BUCKET_SLUG=<COSMIC_BUCKET_SLUG> -e COSMIC_READ_KEY=<COSMIC_READ_KEY> -e COSMIC_WRITE_KEY=<COSMIC_WRITE_KEY> -- npx -y @cosmicjs/mcpReplace <…> with your own values
2Platform CLI: remote server
claude mcp add --transport http cosmic https://mcp.cosmicjs.com/v1/buckets/{bucket_slug}1Platform CLI
codex mcp add cosmic --env COSMIC_BUCKET_SLUG=<COSMIC_BUCKET_SLUG> --env COSMIC_READ_KEY=<COSMIC_READ_KEY> --env COSMIC_WRITE_KEY=<COSMIC_WRITE_KEY> -- npx -y @cosmicjs/mcpReplace <…> with your own values
2Platform CLI: remote server
codex mcp add cosmic --url https://mcp.cosmicjs.com/v1/buckets/{bucket_slug}1Config file
{
"mcpServers": {
"cosmic": {
"command": "npx",
"args": [
"-y",
"@cosmicjs/mcp"
],
"env": {
"COSMIC_BUCKET_SLUG": "<COSMIC_BUCKET_SLUG>",
"COSMIC_READ_KEY": "<COSMIC_READ_KEY>",
"COSMIC_WRITE_KEY": "<COSMIC_WRITE_KEY>"
}
}
}
}Replace <…> with your own values
2Config file
{
"mcpServers": {
"cosmic": {
"url": "https://mcp.cosmicjs.com/v1/buckets/{bucket_slug}"
}
}
}1Config file
{
"servers": {
"cosmic": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@cosmicjs/mcp"
],
"env": {
"COSMIC_BUCKET_SLUG": "<COSMIC_BUCKET_SLUG>",
"COSMIC_READ_KEY": "<COSMIC_READ_KEY>",
"COSMIC_WRITE_KEY": "<COSMIC_WRITE_KEY>"
}
}
}
}Replace <…> with your own values
2Config file
{
"servers": {
"cosmic": {
"type": "http",
"url": "https://mcp.cosmicjs.com/v1/buckets/{bucket_slug}"
}
}
}1Platform CLI
gemini mcp add -e COSMIC_BUCKET_SLUG=<COSMIC_BUCKET_SLUG> -e COSMIC_READ_KEY=<COSMIC_READ_KEY> -e COSMIC_WRITE_KEY=<COSMIC_WRITE_KEY> cosmic npx -y @cosmicjs/mcpReplace <…> with your own values
2Platform CLI: remote server
gemini mcp add -t http cosmic https://mcp.cosmicjs.com/v1/buckets/{bucket_slug}Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Cosmic
How to install Cosmic in Claude Code?
Register the hosted URL with claude mcp add --transport http cosmic https://mcp.cosmicjs.com/v1/buckets/{bucket_slug} or run local stdio using `claude mcp add mcp -e COSMIC_BUCKET_SLUG=<COSMIC_BUCKET_SLUG> -e COSMIC_READ_KEY=<COSMIC_READ_KEY> -e COSMIC_WRITE_KEY=<COSMIC_WRITE_KEY> -- npx -y @cosmicjs/mcp`.
What does the Cosmic MCP server do?
It grants agents direct control over Cosmic CMS records, media uploads, and object schemas, with additional endpoints for AI-driven media generation.
Why are there separate read and write keys?
Cosmic isolates permissions between read and write scopes. Omission of COSMIC_WRITE_KEY restricts the assistant to search and fetch operations, preventing accidental bucket modifications.
