Cosmic MCP Server

A robust, production-ready Model Context Protocol (MCP) server for interacting with the Cosmic headless CMS. This server provides a comprehensive set of tools for creating, reading, updating, and deleting objects, types, and media in your Cosmic bucket.

✨ Features

• Comprehensive Toolset: Full CRUD operations for Cosmic objects, object types, and media.
• Robust Architecture: Built with a clean, three-layer architecture (Server, Services, Repositories).
• Strongly Typed: Written in TypeScript with strict validation using Zod for all inputs.
• Production-Ready: Includes centralized logging, rate-limiting, and graceful error handling.
• Easy to Configure: Simple setup using a .env file for your Cosmic credentials.
• Extensible: Designed to be easily extended with new tools and services.

---

🚀 Getting Started

Prerequisites

• Bun (v1.0 or higher)
• A Cosmic account and bucket.

1. Installation

Clone the repository and install the dependencies:

git clone https://github.com/patgpt/cosmic-mcp.git
cd cosmic-mcp
bun install

2. Configuration

Copy the example environment file and fill in your Cosmic bucket credentials. You can find these in your Cosmic dashboard under Bucket > Settings > API Keys.

cp .env.example .env

Your .env file should look like this:

# .env
COSMIC_BUCKET_SLUG="your-bucket-slug"
COSMIC_READ_KEY="your-read-key"
COSMIC_WRITE_KEY="your-write-key"
DEBUG="false" # Set to "true" for verbose logging

3. Running the Server

Start the MCP server using the following command:

bun start

The server will connect and be ready to receive requests from any MCP-compatible client.

4. Using with MCP Clients

For VS Code (using Claude Dev extension)

Add this configuration to your VS Code settings or Claude Dev configuration:

{
  "mcp": {
    "servers": {
      "Cosmic": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "cosmic-mcp"],
        "env": {
          "COSMIC_BUCKET_SLUG": "your-bucket-slug",
          "COSMIC_READ_KEY": "your-read-key",
          "COSMIC_WRITE_KEY": "your-write-key",
          "DEBUG": "false"
        }
      }
    }
  }
}

For Cursor

Add this configuration to your .cursor/mcp.json file:

{
  "mcpServers": {
    "Cosmic": {
      "command": "npx",
      "args": ["-y", "cosmic-mcp"],
      "env": {
        "COSMIC_BUCKET_SLUG": "your-bucket-slug",
        "COSMIC_READ_KEY": "your-read-key",
        "COSMIC_WRITE_KEY": "your-write-key",
        "DEBUG": "false"
      }
    }
  }
}

Alternative: Local Development

If you're developing locally or prefer to use the local version:

For VS Code:

{
  "mcp": {
    "servers": {
      "Cosmic": {
        "type": "stdio",
        "command": "node",
        "args": ["path/to/cosmic-mcp/dist/server.js"],
        "env": {
          "COSMIC_BUCKET_SLUG": "your-bucket-slug",
          "COSMIC_READ_KEY": "your-read-key",
          "COSMIC_WRITE_KEY": "your-write-key",
          "DEBUG": "true"
        }
      }
    }
  }
}

For Cursor:

{
  "mcpServers": {
    "Cosmic": {
      "command": "node",
      "args": ["path/to/cosmic-mcp/dist/server.js"],
      "env": {
        "COSMIC_BUCKET_SLUG": "your-bucket-slug",
        "COSMIC_READ_KEY": "your-read-key",
        "COSMIC_WRITE_KEY": "your-write-key",
        "DEBUG": "true"
      }
    }
  }
}

Note: Replace your-bucket-slug, your-read-key, and your-write-key with your actual Cosmic bucket credentials. You can find these in your Cosmic dashboard under Bucket > Settings > API Keys.

---

🛠️ Available Tools

This MCP server exposes the following tools. All tools are designed to be called by an AI agent or other MCP client.

For detailed input schemas for each tool, please refer to the 📚 Documentation or the src/manifest.ts file.

---

📚 Documentation

Comprehensive documentation is available at https://patgpt.github.io/cosmic-mcp/

The documentation includes:

• Getting Started Guide - Complete setup and installation instructions
• Configuration Reference - All configuration options and environment variables
• Tools API Documentation - Detailed reference for all available tools
• AI Assistant Prompts - Example prompts for effective AI interaction
• MCP Client Setup - Configuration for VS Code, Cursor, and other MCP clients

Local Documentation

You can also run the documentation locally:

# Install dependencies
npm install

# Start the documentation server
npm run docs:dev

# Build the documentation
npm run docs:build

---

🧪 Running Tests

This project is set up with tests to ensure reliability.

# Run all tests
bun test

---

🤝 Contributing

Contributions are welcome! If you have a suggestion or find a bug, please open an issue to discuss it.

Please see our CONTRIBUTING.md for detailed guidelines on how to contribute to this project, including:

• Development setup and workflow
• Code style and standards
• Testing requirements
• Pull request process
• Release process

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.