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
.env
file 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:
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.
Your .env
file should look like this:
3. Running the Server
Start the MCP server using the following command:
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:
For Cursor
Add this configuration to your .cursor/mcp.json
file:
Alternative: Local Development
If you're developing locally or prefer to use the local version:
For VS Code:
For Cursor:
Note: Replace
your-bucket-slug
,your-read-key
, andyour-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:
🧪 Running Tests
This project is set up with tests to ensure reliability.
🤝 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-qualityProvides a scalable, containerized infrastructure for deploying and managing Model Context Protocol servers with monitoring, high availability, and secure configurations.Last updated -
- AsecurityAlicenseAqualityA Model Context Protocol server that provides a standardized interface for AI models to interact with NASA's vast array of data sources including APOD, Mars Rover photos, satellite imagery, and space weather data.Last updated -2418131TypeScriptISC License
- AsecurityFlicenseAqualityA Model Context Protocol server implementation that provides endpoints for wallet-based authentication, cluster management, and name registration services.Last updated -TypeScript
- -securityAlicense-qualityA server that implements the Model Context Protocol, providing a standardized way to connect AI models to different data sources and tools.Last updated -35TypeScriptMIT License