cargoshipper-mcp by scarr7981 - MCP Server

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:

Clone the repository:
```
cd cargoshipper-mcp
```

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

Configure your APIs:

cp .env.example .env
# Edit .env with your API tokens:
# DIGITALOCEAN_TOKEN=your_token_here
# CLOUDFLARE_API_TOKEN=your_token_here

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!