cargoshipper-mcp 1.0.0

MCP server for Docker, DigitalOcean, and CloudFlare operations

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.

✨ Easy Setup with uvx

CargoShipper is designed to work seamlessly with uvx for easy installation and management, just like mcp-server-git.

Quick Install (Future - when published to PyPI)

# This will work once published to PyPI
uvx install cargoshipper-mcp

# Configure in your .mcp.json
{
  "cargoshipper": {
    "command": "uvx",
    "args": ["cargoshipper-mcp"]
  }
}

Development Setup (Current)

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=[e-mail]
# 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

🔮 Future: PyPI Publication

Once published to PyPI, setup becomes as simple as:

# Install globally
uvx install cargoshipper-mcp

# Or run directly
uvx cargoshipper-mcp

# Configure in .mcp.json
{
  "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!