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.

Tool Name	Description
`list_objects`	List objects, with optional filtering by type, status, and pagination.
`get_object`	Get a specific object by its ID or by its slug and type.
`create_object`	Create a new object.
`update_object`	Update an existing object.
`delete_object`	Delete an object.
`list_object_types`	List all available object types in the bucket.
`search_objects`	Perform a text-based search across objects.
`upload_media`	Upload a media file.
`list_media`	List all media files, with pagination.
`delete_media`	Delete a media file by its ID.

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.

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

A production-ready Model Context Protocol server for interacting with Cosmic headless CMS, providing comprehensive tools for managing objects, types, and media in your Cosmic bucket.

Related MCP Servers

Columbia MCP Server
smithery-ai
-
security
F
license
-
quality
Provides a scalable, containerized infrastructure for deploying and managing Model Context Protocol servers with monitoring, high availability, and secure configurations.
Last updated -
MCP Boilerplate
iamsrikanthnani
-
security
A
license
-
quality
A server that implements the Model Context Protocol, providing a standardized way to connect AI models to different data sources and tools.
Last updated -
2
8
TypeScript
MIT License
MCP REST API Server
vinaykp
-
security
F
license
-
quality
A server implementation of the Model Context Protocol (MCP) that provides REST API endpoints for managing and interacting with MCP resources.
Last updated -
Python
OpenAPI MCP Server
oneWalker
-
security
A
license
-
quality
A server that implements the Model Context Protocol (MCP) with StreamableHTTP transport, enabling standardized interaction with model services through a RESTful API interface.
Last updated -
155
1
JavaScript
MIT License

View all related MCP servers

Cosmic MCP Server