{
  "markdown": "# Cosmic MCP Server\n\nAn 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.\n\n## Features\n\n- **Content Management**: Create, read, update, and delete objects in your Cosmic bucket\n- **Media Management**: Upload, list, and manage media files\n- **Schema Management**: Create and modify object types with custom metafields\n- **AI Generation**: Generate text, images, and videos using Cosmic's AI capabilities\n\n## Hosted endpoint (recommended)\n\nCosmic operates a hosted streamable-HTTP MCP server. No install required.\n\nURL: `https://mcp.cosmicjs.com/v1/buckets/{bucket-slug}`\n\nCosmic uses separate read and write keys per bucket. Authenticate with one of:\n\n```\nAuthorization: Bearer <read_key>                       # read-only tools\nAuthorization: Bearer <read_key>:<write_key>           # full access\n```\n\nYou 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.\n\nUse 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.\n\n### Claude Desktop (remote MCP)\n\nIn Claude Desktop, **Settings -> Connectors -> Add custom connector**, enter:\n- URL: `https://mcp.cosmicjs.com/v1/buckets/your-bucket-slug`\n- Bearer token: `<read_key>` for read-only access, or `<read_key>:<write_key>` for full access\n\n### Cursor (remote MCP)\n\nAdd to `.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"cosmic\": {\n      \"url\": \"https://mcp.cosmicjs.com/v1/buckets/your-bucket-slug\",\n      \"headers\": {\n        \"Authorization\": \"Bearer your-bucket-read-key:your-bucket-write-key\"\n      }\n    }\n  }\n}\n```\n\n## Local installation (stdio)\n\nFor environments without remote MCP support, the same server runs locally over stdio.\n\n### Using npx (recommended)\n\n```bash\nnpx @cosmicjs/mcp\n```\n\n### Global installation\n\n```bash\nnpm install -g @cosmicjs/mcp\ncosmic-mcp\n```\n\n### From source\n\n```bash\ngit clone https://github.com/cosmicjs/mcp.git\ncd mcp\nbun install\nbun run build\n```\n\n## Configuration\n\nThe server requires the following environment variables:\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `COSMIC_BUCKET_SLUG` | Yes | Your Cosmic bucket slug |\n| `COSMIC_READ_KEY` | Yes | Bucket read key for read operations |\n| `COSMIC_WRITE_KEY` | No | Bucket write key for write operations |\n\n### Getting your credentials\n\n1. Log in to your [Cosmic dashboard](https://app.cosmicjs.com)\n2. Navigate to your bucket\n3. Go to **Settings** → **API Access**\n4. Copy your bucket slug, read key, and write key\n\n### Local stdio with Claude Desktop\n\nIf you prefer to run the MCP server locally rather than use the hosted endpoint, add the following to your Claude Desktop configuration file.\n\n**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n**Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"cosmic\": {\n      \"command\": \"npx\",\n      \"args\": [\"@cosmicjs/mcp\"],\n      \"env\": {\n        \"COSMIC_BUCKET_SLUG\": \"your-bucket-slug\",\n        \"COSMIC_READ_KEY\": \"your-read-key\",\n        \"COSMIC_WRITE_KEY\": \"your-write-key\"\n      }\n    }\n  }\n}\n```\n\n### Local stdio with Cursor\n\n```json\n{\n  \"mcpServers\": {\n    \"cosmic\": {\n      \"command\": \"npx\",\n      \"args\": [\"@cosmicjs/mcp\"],\n      \"env\": {\n        \"COSMIC_BUCKET_SLUG\": \"your-bucket-slug\",\n        \"COSMIC_READ_KEY\": \"your-read-key\",\n        \"COSMIC_WRITE_KEY\": \"your-write-key\"\n      }\n    }\n  }\n}\n```\n\n## Available Tools\n\n### Objects\n\n| Tool | Description |\n|------|-------------|\n| `cosmic_objects_list` | List objects with optional type filter, status, and pagination |\n| `cosmic_objects_get` | Get a single object by ID or slug |\n| `cosmic_objects_create` | Create a new object (requires write key) |\n| `cosmic_objects_update` | Update an existing object (requires write key) |\n| `cosmic_objects_delete` | Delete an object (requires write key) |\n\n### Media\n\n| Tool | Description |\n|------|-------------|\n| `cosmic_media_list` | List media files with optional folder filter |\n| `cosmic_media_get` | Get media details by ID |\n| `cosmic_media_upload` | Upload media from URL or base64 (requires write key) |\n| `cosmic_media_delete` | Delete a media file (requires write key) |\n\n### Object Types\n\n| Tool | Description |\n|------|-------------|\n| `cosmic_types_list` | List all object types in the bucket |\n| `cosmic_types_get` | Get object type schema by slug |\n| `cosmic_types_create` | Create a new object type (requires write key) |\n| `cosmic_types_update` | Update object type schema (requires write key) |\n| `cosmic_types_delete` | Delete an object type (requires write key) |\n\n### AI Generation\n\n| Tool | Description |\n|------|-------------|\n| `cosmic_ai_generate_text` | Generate text content using AI |\n| `cosmic_ai_generate_image` | Generate and upload an AI image (requires write key) |\n| `cosmic_ai_generate_video` | Generate and upload an AI video (requires write key) |\n\n### Content Blocks\n\n| Tool | Description |\n|------|-------------|\n| `cosmic_blocks_list` | List the bucket's reusable rich-text Content Blocks (the `{{name /}}` tokens available in rich-text fields) |\n\n## Example Prompts\n\nHere are some example prompts you can use with Claude or Cursor:\n\n### Content Management\n\n```\nList all blog posts in my Cosmic bucket\n```\n\n```\nCreate a new blog post titled \"Getting Started with MCP\" with the content \"This is an introduction to the Model Context Protocol...\"\n```\n\n```\nUpdate the blog post with ID \"abc123\" to change its status to published\n```\n\n### Media\n\n```\nShow me all images in the \"blog-images\" folder\n```\n\n```\nUpload this image URL to my media library: https://example.com/image.jpg\n```\n\n### Schema Management\n\n```\nShow me all object types in my bucket\n```\n\n```\nCreate a new object type called \"Products\" with fields for name, price, description, and image\n```\n\n### AI Generation\n\n```\nGenerate a product description for a wireless bluetooth headphone\n```\n\n```\nGenerate an image of a futuristic city skyline at sunset and upload it to my media library\n```\n\n## Development\n\n### Build\n\n```bash\nbun run build\n```\n\nThis produces two binaries:\n- `dist/stdio.js` - npm-published stdio entry (`bin: cosmic-mcp`)\n- `dist/http.js` - hosted streamable-HTTP entry (deployed to ECS Fargate)\n\n### Watch mode (stdio)\n\n```bash\nbun run dev\n```\n\n### Run locally (stdio)\n\n```bash\nCOSMIC_BUCKET_SLUG=your-bucket \\\nCOSMIC_READ_KEY=your-read-key \\\nCOSMIC_WRITE_KEY=your-write-key \\\nbun run start\n```\n\n### Run locally (HTTP)\n\n```bash\nbun run dev:http\n# Server listens on http://localhost:3000\n# POST http://localhost:3000/v1/buckets/{slug} with Authorization: Bearer <key>\n```\n\n### Deployment\n\nPushes to `main` deploy to `https://mcp.cosmicjs.com` via GitHub Actions. Workflow: [`.github/workflows/deploy.yml`](.github/workflows/deploy.yml).\n\n### Releasing to npm\n\nReleases 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`).\n\nTo cut a release, run one command from a clean `main`:\n\n```bash\nbun run release\n```\n\nThis 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).\n\nDo 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`.\n\n### Publishing to the MCP registry\n\nThe server is listed on [registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io) under the `com.cosmicjs` namespace, described by [`server.json`](./server.json).\n\nOrder 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.\n\nOne-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):\n\n```bash\nopenssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:secp384r1 -out key.pem\n\nPUBLIC_KEY=\"$(openssl ec -in key.pem -text -noout -conv_form compressed | grep -A4 \"pub:\" | tail -n +2 | tr -d ' :\\n' | xxd -r -p | base64)\"\necho \"cosmicjs.com. IN TXT \\\"v=MCPv1; k=ecdsap384; p=${PUBLIC_KEY}\\\"\"\n```\n\nAdd 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`.\n\nThen, after each npm release, publish the listing (`brew install mcp-publisher` first):\n\n```bash\nPRIVATE_KEY=\"$(openssl ec -in ~/.cosmic-mcp/key.pem -noout -text | grep -A4 \"priv:\" | tail -n +2 | tr -d ' :\\n')\"\nmcp-publisher login dns --algorithm ecdsap384 --domain cosmicjs.com --private-key \"${PRIVATE_KEY}\"\nmcp-publisher publish\n```\n\n`--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.\n\n## API Reference\n\nFor more information about the Cosmic API, see:\n\n- [Cosmic Documentation](https://www.cosmicjs.com/docs)\n- [API Reference](https://www.cosmicjs.com/docs/api)\n- [JavaScript SDK](https://www.cosmicjs.com/docs/api)\n\n## License\n\nMIT\n\n## Contributing\n\nContributions are welcome! Please open an issue or submit a pull request.\n\n## Support\n\n- [Cosmic Documentation](https://www.cosmicjs.com/docs)\n- [Cosmic Discord](https://discord.gg/cosmic)\n- [GitHub Issues](https://github.com/cosmicjs/cosmic-mcp/issues)\n",
  "bytes": 10621,
  "sha": "42e57843a12f58119109c76efe1b194716e16fbfe5986c0ebc8f43818297d2fd",
  "repo_slug": "cosmicjs/mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_com_cosmicjs_mcp_9e7232ec/readme"
}