# Cosmic

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/cosmicjs/mcp  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/cosmic

## Description
Manage Cosmic CMS content, media, object types, and AI generation from any MCP client.

## Claude Desktop Quick Installation
Heuristic fallback — verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low):

```json
"mcpServers": {
  "cosmic": {
    "command": "npx",
    "args": ["-y","cosmic"]
  }
}
```

## Documentation & README

# Cosmic MCP Server

An MCP (Model Context Protocol) server that exposes [Cosmic CMS](https://www.cosmicjs.com) 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`:

```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)

```bash
npx @cosmicjs/mcp
```

### Global installation

```bash
npm install -g @cosmicjs/mcp
cosmic-mcp
```

### From source

```bash
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](https://app.cosmicjs.com)
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`

```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

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

## 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) |

### 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

```bash
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)

```bash
bun run dev
```

### Run locally (stdio)

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

### Run locally (HTTP)

```bash
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`](.github/workflows/deploy.yml).

### Releasing to npm

Releases are driven by [Changesets](https://github.com/changesets/changesets). Every change that should ship adds a changeset (`bunx changeset`) describing the bump (`patch` | `minor` | `major`).

To cut a release, run one command from a clean `main`:

```bash
bun run release
```

This consumes the pending changesets to bump the version, refreshes the lockfile, commits `chore(release): vX.Y.Z`, then tags and pushes. It prompts once before the tag push (pass `-- --yes` to skip). Pushing the tag triggers the [`publish.yml`](.github/workflows/publish.yml) workflow, which verifies the tag matches `package.json`, builds, and runs `npm publish --provenance --access public` (requires the `NPM_TOKEN` repo secret).

Do not hand-edit the `version` field in `package.json`; let the changeset bump it. The release also runs `scripts/sync-version.mjs`, which copies the new version into `server.json` and `SERVER_VERSION` in `src/server.ts` so all three always agree. If you ever need to publish directly from your machine (with a local npm token, no provenance), `bun run release:direct` runs `changeset publish`.

### Publishing to the MCP registry

The server is listed on [registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io) under the `com.cosmicjs` namespace, described by [`server.json`](./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):

```bash
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):

```bash
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:

- [Cosmic Documentation](https://www.cosmicjs.com/docs)
- [API Reference](https://www.cosmicjs.com/docs/api)
- [JavaScript SDK](https://www.cosmicjs.com/docs/api)

## License

MIT

## Contributing

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

## Support

- [Cosmic Documentation](https://www.cosmicjs.com/docs)
- [Cosmic Discord](https://discord.gg/cosmic)
- [GitHub Issues](https://github.com/cosmicjs/cosmic-mcp/issues)