cargoshipper-mcp

# CargoShipper MCP Server [](https://www.python.org/downloads/) [](https://modelcontextprotocol.io/) [](https://pypi.org/project/cargoshipper-mcp/) [](https://github.com/astral-sh/uvx) A comprehensive MCP (Model Context Protocol) server that provides Claude with direct access to Docker, DigitalOcean, and CloudFlare APIs for infrastructure management and automation. ## ⚠️ **IMPORTANT SAFETY WARNING** **USE AT YOUR OWN RISK**: This tool gives AI models direct access to infrastructure management APIs that can: - Create, modify, or delete cloud resources (potentially incurring costs) - Modify DNS settings (potentially breaking domains) - Manage Docker containers and images (potentially affecting running services) - Execute destructive operations on your infrastructure **Before using:** - Ensure you understand the capabilities and risks of each API - Start with non-production environments only - Review all operations before execution in production - Monitor costs and resource usage carefully - Have backup and recovery procedures in place **AI models may:** - Misinterpret instructions and perform unintended operations - Make mistakes in resource configuration or deletion - Execute multiple operations when only one was intended - Struggle with complex multi-step procedures requiring human judgment **Recommended safety measures:** - Use dedicated development/testing accounts with spending limits - Implement least-privilege API tokens with restricted permissions - Monitor all operations through cloud provider dashboards - Test operations in isolated environments first - Keep backups of critical configurations and data ## 🤖 **VIBECODE FRIENDLY PROJECT** This project welcomes contributions from AI/LLM agents! **Pull requests from Claude, GPT, and other AI models are actively encouraged.** **Guidelines for AI contributors:** - Follow existing code patterns and documentation standards - Include comprehensive commit messages explaining changes - Test changes thoroughly before submitting PRs - Update documentation when adding new features ## ✨ Easy Setup with uvx CargoShipper is available on PyPI and works seamlessly with `uvx` for easy installation and management, just like `mcp-server-git`. ### Quick Install from PyPI ```bash # Run directly (recommended) uvx cargoshipper-mcp # Configure in your .mcp.json { "mcpServers": { "cargoshipper": { "command": "uvx", "args": ["cargoshipper-mcp"] } } } ``` ### Development Setup For local development and testing: 1. **Clone the repository:** ```bash cd cargoshipper-mcp ``` 2. **Install dependencies:** ```bash pip install -r requirements.txt # or create a virtual environment first python3 -m venv .venv source .venv/bin/activate # Linux/Mac pip install -r requirements.txt ``` 3. **Configure your APIs:** ```bash cp .env.example .env # Edit .env with your API tokens: # DIGITALOCEAN_TOKEN=your_token_here # CLOUDFLARE_API_TOKEN=your_token_here ``` 4. **Use the development MCP configuration:** ```bash # Use .mcp.dev.json for local development cp .mcp.dev.json .mcp.json ``` ## 🐳 Docker Integration - **Container Management**: Full lifecycle (create, start, stop, remove, logs) - **Image Operations**: List, pull, and manage Docker images - **System Information**: Docker system stats and health - **Resource Monitoring**: Container resource usage and status ## 🌊 DigitalOcean Integration - **Droplet Management**: Complete droplet lifecycle management - **DNS Management**: Full DNS record CRUD operations - **Account Information**: Access account details and billing - **Image Management**: Work with distributions and custom snapshots ## ☁️ CloudFlare Integration - **Zone Management**: Create and configure CloudFlare zones - **DNS Operations**: Advanced DNS with proxy settings - **Cache Control**: Purge cache by URL, tags, or everything - **Analytics**: Traffic and performance analytics - **Security Settings**: SSL, security levels, firewall rules ## 🔧 Available Tools & Resources **30 Tools Total:** - **Docker (9 tools)**: `docker_run_container`, `docker_list_containers`, etc. - **DigitalOcean (10 tools)**: `do_create_droplet`, `do_list_dns_records`, etc. - **CloudFlare (11 tools)**: `cf_create_zone`, `cf_purge_cache`, etc. **17 Resources Total:** - `docker://containers` - All containers with status - `digitalocean://droplets` - All droplets with costs - `cloudflare://zones` - All zones with analytics - And many more... ## 📋 Configuration Files ### Production (.mcp.json) ```json { "mcpServers": { "cargoshipper": { "command": "uvx", "args": ["cargoshipper-mcp"] } } } ``` ### Development (.mcp.dev.json) ```json { "mcpServers": { "cargoshipper": { "command": "python", "args": ["-m", "cargoshipper_mcp.server"], "cwd": ".", "env": { "PYTHONPATH": "." } } } } ``` ## 🔑 API Credentials Setup Create `.env` file or `~/.config/cargoshipper-mcp/.env`: ```env # DigitalOcean API Token DIGITALOCEAN_TOKEN=your_digitalocean_token_here # CloudFlare API Token (recommended) CLOUDFLARE_API_TOKEN=your_cloudflare_token_here # Alternative: CloudFlare Email + Global API Key # CLOUDFLARE_EMAIL=your@email.com # CLOUDFLARE_API_KEY=your_global_api_key ``` **Getting API Tokens:** - **DigitalOcean**: [API Tokens Page](https://cloud.digitalocean.com/account/api/tokens) - **CloudFlare**: [API Tokens Page](https://dash.cloudflare.com/profile/api-tokens) ## 🚀 Usage Examples Once configured, Claude will have access to infrastructure operations: ``` # Docker examples "Run an nginx container on port 8080" "List all running containers" "Get logs from container abc123" # DigitalOcean examples "Create a small droplet in NYC3" "List all my droplets and their costs" "Add an A record for api.example.com" # CloudFlare examples "Create a new zone for mysite.com" "Purge all cache for example.com" "Show me analytics for the last 24 hours" ``` ## 📁 Project Structure ``` cargoshipper-mcp/ ├── cargoshipper_mcp/ # Main package (renamed from src/) │ ├── server.py # MCP server entry point │ ├── config/ # Configuration with multi-path .env loading │ ├── tools/ # API operation tools │ │ ├── docker.py # Docker operations │ │ ├── digitalocean.py # DigitalOcean operations │ │ └── cloudflare.py # CloudFlare operations │ ├── resources/ # Read-only data access │ └── utils/ # Shared utilities ├── .mcp.json # Production MCP config (uvx) ├── .mcp.dev.json # Development MCP config (local python) ├── pyproject.toml # Python packaging (uvx compatible) ├── requirements.txt # Dependencies └── install.sh # uvx installation script ``` ## 🌍 Published on PyPI CargoShipper MCP is now available on PyPI! Access it at: https://pypi.org/project/cargoshipper-mcp/ Setup is as simple as: ```bash # Run directly (most common) uvx cargoshipper-mcp # Configure in .mcp.json { "mcpServers": { "cargoshipper": { "command": "uvx", "args": ["cargoshipper-mcp"] } } } ``` ## 🛠️ Development ### Package Structure - Uses proper Python packaging with `pyproject.toml` - Console entry point: `cargoshipper-mcp = "cargoshipper_mcp.server:main"` - Multi-path environment loading for uvx compatibility - Type hints and comprehensive error handling throughout ### Testing ```bash python test_server.py # Validates imports and configuration ``` This approach follows the same pattern as `mcp-server-git` and other uvx-compatible MCP servers, making it extremely easy to install and use once published!