CargoShipper MCP Server

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

# 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:

   cd cargoshipper-mcp
   

2. Install dependencies:

   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:

   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:

   # 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)

{
  "mcpServers": {
    "cargoshipper": {
      "command": "uvx", 
      "args": ["cargoshipper-mcp"]
    }
  }
}

Development (.mcp.dev.json)

{
  "mcpServers": {
    "cargoshipper": {
      "command": "python",
      "args": ["-m", "cargoshipper_mcp.server"],
      "cwd": ".",
      "env": {
        "PYTHONPATH": "."
      }
    }
  }
}

🔑 API Credentials Setup

Create .env file or ~/.config/cargoshipper-mcp/.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
• CloudFlare: API Tokens Page

🚀 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:

# 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

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!