-
securityF
license-
qualityProvides a scalable, containerized infrastructure for deploying and managing Model Context Protocol servers with monitoring, high availability, and secure configurations.
Last updated -
Used as the runtime environment for the server, requiring version 1.0 or higher.
Integrates with Codecov for code coverage reporting as indicated by the coverage badge.
Uses .env files for configuration management of Cosmic credentials and settings.
Integrates with GitHub for CI/CD workflows as shown by the build and test status badges.
Provides the package via npm registry for easy installation.
Displays status badges from Shields.io to show build status, license, and other metrics.
Built with TypeScript to provide strong typing for the application.
Employs Zod for strict validation of all inputs to the server.
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
.envfile for your Cosmic credentials.Extensible: Designed to be easily extended with new tools and services.
🚀 Getting Started
Prerequisites
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, andyour-write-keywith 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, with optional filtering by type, status, and pagination. |
| Get a specific object by its ID or by its slug and type. |
| Create a new object. |
| Update an existing object. |
| Delete an object. |
| List all available object types in the bucket. |
| Perform a text-based search across objects. |
| Upload a media file. |
| List all media files, with pagination. |
| 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
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
- -securityFlicense-qualityA server implementation of the Model Context Protocol (MCP) that provides REST API endpoints for managing and interacting with MCP resources.Last updated -
- -securityFlicense-qualityA comprehensive Model Context Protocol server that provides over 50 file and system management tools for AI models, including navigation, file operations, search, compression, and system information capabilities.Last updated -
- -securityAlicense-qualityA comprehensive Model Context Protocol server providing capabilities for web scraping, data analysis, system monitoring, file operations, API integrations, and report generation.