Meta Agent Tools
PT

Back to the catalog

Cosmic

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

Open source Repository Open in the app JSON README (API)

About

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

Details

Kind
MCP servers
Topic
Social & content
Publisher
com.cosmicjs
Origin
official
Category
ferramentas
Transport
http
Version
1.6.0
Stars
1
Last push
2026-07-31T03:50:30Z
Repository state
ativo
Language
TypeScript
License
MIT
Added
2026-08-29 03:01:04
Updated
2026-08-29 03:01:04
Origin id
com.cosmicjs/mcp

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)

More