How do I install Cosmic?

Copy the http config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Cosmic need an API key?

The publisher lists these environment variables: COSMIC_BUCKET_SLUG, COSMIC_READ_KEY, COSMIC_WRITE_KEY.

When was Cosmic last checked?

Last checked 2026-10-23. Manage Cosmic CMS content, media, object types, and AI generation from any MCP client.

Cosmic MCP server

Power your agent

Add this server

The publisher's own URL. Not a PlugMCP endpoint.

Add to Cursor Add in Claude Add to VS Code Run on PlugMCP

Host a copy with our keys and logs.

Server URL

https://mcp.cosmicjs.com/v1/buckets/{bucket_slug}

Credentials from the publisher

COSMIC_BUCKET_SLUG — Slug of the Cosmic bucket to operate on
COSMIC_READ_KEY — Bucket read key. Enables the read-only tools
COSMIC_WRITE_KEY — Bucket write key. Required for create, update, delete, and AI generation

The Claude button above opens Claude with the name and URL filled in. You still confirm it there.

shClaude Code

1claude mcp add --transport http com.cosmicjs-mcp https://mcp.cosmicjs.com/v1/buckets/{bucket_slug}

Run in a terminal.

jsonClaude Desktop

1{2  "mcpServers": {3    "com.cosmicjs-mcp": {4      "command": "npx",5      "args": [6        "-y",7        "mcp-remote",8        "https://mcp.cosmicjs.com/v1/buckets/{bucket_slug}"9      ]10    }11  }12}

claude_desktop_config.json

Remote · HTTPPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Remote

Transport: http
Version

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

Cosmic MCP Server

Cosmic is a headless CMS with a hosted MCP server, in-product AI workflows, and agent signup. An agent can read and write content, generate text, images, video, and audio into the media library, chain content, code, and browser steps, or provision a new project with no existing account.

Capability table: https://www.cosmicjs.com/ai-cms

Signup MCP (no credentials): https://mcp.cosmicjs.com/v1/agent

Features

Content Management: Create, read, update, and delete objects in your Cosmic bucket
Media Management: Upload, list, and manage media files
Schema Management: Create and modify object types with custom metafields
AI Generation: Generate text, images, and videos using Cosmic's AI capabilities

Hosted endpoint (recommended)

Cosmic operates a hosted streamable-HTTP MCP server. No install required.

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

Cosmic uses separate read and write keys per bucket. Authenticate with one of:

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

You can also send the write key out-of-band via the X-Cosmic-Write-Key header if your client can't colon-pack the bearer token. Keys are issued in your bucket's API Access settings in the Cosmic dashboard.

Use the read key for read-only access (list/get tools), or the write key for full access including object creation, media upload, and AI generation.

Claude Desktop (remote MCP)

In Claude Desktop, Settings -> Connectors -> Add custom connector, enter:

URL: https://mcp.cosmicjs.com/v1/buckets/your-bucket-slug
Bearer token: <read_key> for read-only access, or <read_key>:<write_key> for full access

Cursor (remote MCP)

Add to .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"
      }
    }
  }
}

Local installation (stdio)

For environments without remote MCP support, the same server runs locally over stdio.

Using npx (recommended)

npx @cosmicjs/mcp

Global installation

npm install -g @cosmicjs/mcp
cosmic-mcp

From source

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

Configuration

The server requires the following environment variables:

Variable	Required	Description
`COSMIC_BUCKET_SLUG`	Yes	Your Cosmic bucket slug
`COSMIC_READ_KEY`	Yes	Bucket read key for read operations
`COSMIC_WRITE_KEY`	No	Bucket write key for write operations

Getting your credentials

Log in to your Cosmic dashboard
Navigate to your bucket
Go to Settings → API Access
Copy your bucket slug, read key, and write key

Local stdio with Claude Desktop

If you prefer to run the MCP server locally rather than use the hosted endpoint, add the following to your Claude Desktop configuration file.

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

Local stdio with Cursor

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

Available Tools

Objects

Tool	Description
`cosmic_objects_list`	List objects with optional type filter, status, and pagination
`cosmic_objects_get`	Get a single object by ID or slug
`cosmic_objects_create`	Create a new object (requires write key)
`cosmic_objects_update`	Update an existing object (requires write key)
`cosmic_objects_delete`	Delete an object (requires write key)

Media

Tool	Description
`cosmic_media_list`	List media files with optional folder filter
`cosmic_media_get`	Get media details by ID
`cosmic_media_upload`	Upload media from URL or base64 (requires write key)
`cosmic_media_delete`	Delete a media file (requires write key)

Object Types

Tool	Description
`cosmic_types_list`	List all object types in the bucket
`cosmic_types_get`	Get object type schema by slug
`cosmic_types_create`	Create a new object type (requires write key)
`cosmic_types_update`	Update object type schema (requires write key)
`cosmic_types_delete`	Delete an object type (requires write key)

AI Generation

Tool	Description
`cosmic_ai_generate_text`	Generate text content using AI
`cosmic_ai_generate_image`	Generate and upload an AI image or SVG (requires write key)
`cosmic_ai_generate_video`	Generate and upload an AI video (requires write key)

Content Blocks

Tool	Description
`cosmic_blocks_list`	List the bucket's reusable rich-text Content Blocks (the `{{name /}}` tokens available in rich-text fields)

Example Prompts

Here are some example prompts you can use with Claude or Cursor:

Content Management

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

Media

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

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

Schema Management

Show me all object types in my bucket

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

AI Generation

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

Development

Build

bun run build

This produces two binaries:

dist/stdio.js - npm-published stdio entry (bin: cosmic-mcp)
dist/http.js - hosted streamable-HTTP entry (deployed to ECS Fargate)

Watch mode (stdio)

bun run dev

Run locally (stdio)

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

Run locally (HTTP)

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

Deployment

Pushes to main deploy to https://mcp.cosmicjs.com via GitHub Actions. Workflow: .github/workflows/deploy.yml.

Releasing to npm

Releases use the same Changesets flow as @cosmicjs/sdk. Every change that should ship adds a changeset (bunx changeset) describing the bump (patch | minor | major). Do not hand-edit the version field in package.json.

Merge the feature PR to main. Package Checks must pass.
CI opens or updates a Version Packages PR. That PR consumes the changeset, bumps the version, updates CHANGELOG.md, and runs scripts/sync-version.mjs so server.json and SERVER_VERSION stay in sync.
Merging the Version Packages PR publishes to npm via publish.yml (requires the NPM_TOKEN repo secret).

Do not push v*.*.* tags by hand. Hosted MCP deploys from main / staging separately via deploy.yml.

Publishing to the MCP registry

The server is listed on registry.modelcontextprotocol.io under the com.cosmicjs namespace, described by server.json.

Order matters: the registry verifies the listing against what is actually on npm, so release to npm first and publish the listing second. mcpName in package.json must always equal name in server.json, which is how the registry proves we own the npm package.

One-time setup to prove domain ownership. This uses ECDSA P-384 because macOS ships LibreSSL, which cannot generate Ed25519 keys (brew install openssl@3 if you prefer Ed25519):

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

Add that TXT record on the apex of cosmicjs.com. A selector such as _mcp-auth.cosmicjs.com will not be found and fails with a generic signature error. The apex TXT set also holds the SPF and Google verification records, so append to it rather than replacing it. Keep key.pem out of the repo; it lives in ~/.cosmic-mcp/key.pem.

Then, after each npm release, publish the listing (brew install mcp-publisher first):

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 is required. The publisher defaults to ed25519 and rejects the P-384 key with invalid seed length: expected 32 bytes, got 48, which reads like a corrupt key rather than a wrong algorithm.

API Reference

For more information about the Cosmic API, see:

License

MIT

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install Cosmic?

Does Cosmic need an API key?

What transport does Cosmic use?

When was Cosmic last checked?

Documentation

Cosmic MCP Server

Features

Hosted endpoint (recommended)

Claude Desktop (remote MCP)

Cursor (remote MCP)

Local installation (stdio)

Using npx (recommended)

Global installation

From source

Configuration

Getting your credentials

Local stdio with Claude Desktop

Local stdio with Cursor

Available Tools

Objects

Media

Object Types

AI Generation

Content Blocks

Example Prompts

Content Management

Media

Schema Management

AI Generation

Development

Build

Watch mode (stdio)

Run locally (stdio)

Run locally (HTTP)

Deployment

Releasing to npm

Publishing to the MCP registry

API Reference

License

Contributing

Support