Manage headless CMS content, media, schemas, and trigger AI generation for text, images, and video directly from an AI client.
Also known as cosmicjs/mcp, mcp, @cosmicjs/mcp
- Stars
- 1
- Tools
- 18
- Downloads, 30 days
- 542
- Latest version
- 1.7.1
- Last commit
- Nov 13, 2026
- License
- MIT
What is Cosmic MCP?
Cosmic manages headless CMS content, media, schemas, and trigger AI generation for text, images, and video directly from an AI client. It exposes 18 tools, such as cosmic_objects_list, cosmic_objects_get, cosmic_objects_create.
Summary generated from the project's README
About Cosmic MCP server
Cosmic provides a way for developers to manage headless CMS content through an AI client. It allows users to interact with their Cosmic buckets to perform content management tasks, handle media files, and modify object type schemas. The server supports both a hosted HTTP endpoint for easy remote connection and a local installation via stdio using npx or global npm installation.
Users can connect via Claude Desktop or Cursor by providing a bucket slug and authentication keys. The system uses a read key for list and get tools, while a write key is required for creating objects, uploading media, and triggering AI generation. Beyond standard CRUD operations, the server includes specialized tools for generating text, images, and video directly into the media library. This makes it possible to automate content workflows and schema updates through natural language commands.
What you can do with it
- 1Automated Content CreationAn AI agent can create and update blog posts or other objects within a specific bucket.
- 2AI Media GenerationYou can instruct an AI client to generate and upload new images or videos to your media library.
- 3Schema and Type ManagementDevelopers can programmatically define new object types and custom metafields.
- 4Media Library OrganizationUsers can manage their media assets by listing files or uploading new content from URLs.
Written from the project's README. Every use case is checked against a quote from it.
How to install Cosmic MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Cosmic MCP in Claude Code
$ claude mcp add --env 'COSMIC_READ_KEY=<YOUR_COSMIC_READ_KEY>' --env 'COSMIC_BUCKET_SLUG=<COSMIC_BUCKET_SLUG>' --env 'COSMIC_WRITE_KEY=<YOUR_COSMIC_WRITE_KEY>' mcp -- npx -y @cosmicjs/mcpInstall Cosmic MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"@cosmicjs/mcp"
],
"env": {
"COSMIC_READ_KEY": "<YOUR_COSMIC_READ_KEY>",
"COSMIC_BUCKET_SLUG": "<COSMIC_BUCKET_SLUG>",
"COSMIC_WRITE_KEY": "<YOUR_COSMIC_WRITE_KEY>"
}
}
}
}Install Cosmic MCP in VS Code
.vscode/mcp.json
{
"servers": {
"mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@cosmicjs/mcp"
],
"env": {
"COSMIC_READ_KEY": "<YOUR_COSMIC_READ_KEY>",
"COSMIC_BUCKET_SLUG": "<COSMIC_BUCKET_SLUG>",
"COSMIC_WRITE_KEY": "<YOUR_COSMIC_WRITE_KEY>"
}
}
}
}Install Cosmic MCP in VS Code CLI
$ code --add-mcp '{"name":"mcp","type":"stdio","command":"npx","args":["-y","@cosmicjs/mcp"],"env":{"COSMIC_READ_KEY":"<YOUR_COSMIC_READ_KEY>","COSMIC_BUCKET_SLUG":"<COSMIC_BUCKET_SLUG>","COSMIC_WRITE_KEY":"<YOUR_COSMIC_WRITE_KEY>"}}'Install Cosmic MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"@cosmicjs/mcp"
],
"env": {
"COSMIC_READ_KEY": "<YOUR_COSMIC_READ_KEY>",
"COSMIC_BUCKET_SLUG": "<COSMIC_BUCKET_SLUG>",
"COSMIC_WRITE_KEY": "<YOUR_COSMIC_WRITE_KEY>"
}
}
}
}Install Cosmic MCP in Codex
$ codex mcp add mcp --env 'COSMIC_READ_KEY=<YOUR_COSMIC_READ_KEY>' --env 'COSMIC_BUCKET_SLUG=<COSMIC_BUCKET_SLUG>' --env 'COSMIC_WRITE_KEY=<YOUR_COSMIC_WRITE_KEY>' -- npx -y @cosmicjs/mcpInstall Cosmic MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.mcp] command = "npx" args = ["-y", "@cosmicjs/mcp"] [mcp_servers.mcp.env] COSMIC_READ_KEY = "<YOUR_COSMIC_READ_KEY>" COSMIC_BUCKET_SLUG = "<COSMIC_BUCKET_SLUG>" COSMIC_WRITE_KEY = "<YOUR_COSMIC_WRITE_KEY>"
Install Cosmic MCP in Gemini CLI
$ gemini mcp add -s user -e 'COSMIC_READ_KEY=<YOUR_COSMIC_READ_KEY>' -e 'COSMIC_BUCKET_SLUG=<COSMIC_BUCKET_SLUG>' -e 'COSMIC_WRITE_KEY=<YOUR_COSMIC_WRITE_KEY>' mcp npx -- -y @cosmicjs/mcpInstall Cosmic MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"@cosmicjs/mcp"
],
"env": {
"COSMIC_READ_KEY": "<YOUR_COSMIC_READ_KEY>",
"COSMIC_BUCKET_SLUG": "<COSMIC_BUCKET_SLUG>",
"COSMIC_WRITE_KEY": "<YOUR_COSMIC_WRITE_KEY>"
}
}
}
}Needs a key before it starts
Started on 16 Nov 2026 with no keys, it stopped and asked for one, so a client sees no tools until you set the variables above.
Cosmic MCP tools 18
Detected from the READMEcosmic_objects_listcosmic_objects_getcosmic_objects_createcosmic_objects_updatecosmic_objects_deletecosmic_media_listcosmic_media_getcosmic_media_uploadcosmic_media_deletecosmic_types_listcosmic_types_getcosmic_types_create
Show all 18 toolsShow fewer tools
cosmic_types_updatecosmic_types_deletecosmic_ai_generate_textcosmic_ai_generate_imagecosmic_ai_generate_videocosmic_blocks_list
Configuration
COSMIC_READ_KEYRequiredSecretBucket read key. Enables the read-only tools
COSMIC_BUCKET_SLUGRequiredSlug of the Cosmic bucket to operate on
COSMIC_WRITE_KEYSecretBucket write key. Required for create, update, delete, and AI generation
PRIVATE_KEYPUBLIC_KEY
Automated checks
Ran Nov 12, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSPass
- Destructive tools are labelledPass
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHubCosmic 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 runsscripts/sync-version.mjssoserver.jsonandSERVER_VERSIONstay in sync. - Merging the Version Packages PR publishes to npm via
publish.yml(requires theNPM_TOKENrepo 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.
Support
Cosmic MCP questions
How do I add Cosmic MCP to Claude Code?
Run claude mcp add --env 'COSMIC_READ_KEY=<YOUR_COSMIC_READ_KEY>' --env 'COSMIC_BUCKET_SLUG=<COSMIC_BUCKET_SLUG>' --env 'COSMIC_WRITE_KEY=<YOUR_COSMIC_WRITE_KEY>' mcp -- npx -y @cosmicjs/mcp in your terminal. Add --scope user to make it available in every project.
How do I add Cosmic MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Cosmic MCP provide?
It exposes 18 tools, including cosmic_objects_list, cosmic_objects_get, cosmic_objects_create, cosmic_objects_update, cosmic_objects_delete.
How do I authenticate with the Cosmic MCP server?
You can authenticate using a Bearer token with either a read key for read-only access or a colon-packed read and write key for full access.
Can I use the Cosmic MCP server without installing it locally?
Yes, Cosmic operates a hosted streamable-HTTP MCP server that requires no installation.