Cosmic MCP Server

An MCP (Model Context Protocol) server that exposes Cosmic CMS functionality as tools for AI assistants. Manage your content, media, object types, and generate AI content directly through Claude, Cursor, or any MCP-compatible client.

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

1. Log in to your Cosmic dashboard
2. Navigate to your bucket
3. Go to Settings → API Access
4. 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 (requires write key) | | cosmic_ai_generate_video | Generate and upload an AI video (requires write key) |

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

The npm package is published by the publish.yml workflow when a vX.Y.Z tag is pushed:

# After bumping the version field in package.json and merging to main:
git checkout main && git pull
git tag v1.2.0
git push origin v1.2.0

The workflow verifies the tag matches package.json version, builds, and runs npm publish --provenance --access public. Requires the NPM_TOKEN repo secret.

API Reference

For more information about the Cosmic API, see:

• Cosmic Documentation
• API Reference
• JavaScript SDK

License

MIT

Contributing

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

Support

• Cosmic Documentation
• Cosmic Discord
• GitHub Issues