DuploCloud Docker MCP Server

MCP server that exposes DuploCloud infrastructure management as tools consumable via Docker MCP Toolkit.

Tools (31 total)

Category	Tools
Tenants	tenant_list, tenant_get, tenant_create, tenant_delete
Services	service_list, service_get, service_create, service_update, service_delete, service_restart
Hosts	host_list, host_get, host_create, host_delete, host_reboot
Databases	database_list, database_get, database_create, database_update, database_delete
Storage	bucket_list, bucket_get, bucket_create, bucket_update, bucket_delete
Containers	ecs_service_list, ecs_task_def_list, ecs_task_list, ecs_task_run, ecs_service_update, ecs_service_delete

Setup

Prerequisites

• Python 3.13+
• uv
• DuploCloud portal access with an API token

Environment Variables

export DUPLO_HOST=https://your-company.duplocloud.net
export DUPLO_TOKEN=your-api-token
export DUPLO_TENANT=default  # optional

Install & Run

uv sync
uv run main.py

Docker

docker build -f docker/Dockerfile -t duplocloud-mcp .
docker run -i --rm \
  -e DUPLO_HOST=https://your-company.duplocloud.net \
  -e DUPLO_TOKEN=your-api-token \
  duplocloud-mcp

Docker MCP Toolkit

docker mcp server add duplocloud-mcp

Tool Reference

Tenants

Tool	Parameters	Description
tenant_list	—	List all tenants accessible in the DuploCloud portal
tenant_get	name	Get details of a specific tenant by name
tenant_create	account_name, plan_id	Create a new tenant
tenant_delete	name	Delete a tenant by name

Services

Tool	Parameters	Description
service_list	tenant_id	List all services in a tenant
service_get	tenant_id, name	Get details of a specific service
service_create	tenant_id, name, image, replicas=1	Create a new service
service_update	tenant_id, name, image?, replicas?	Update service image and/or replicas
service_delete	tenant_id, name	Delete a service
service_restart	tenant_id, name	Restart a service (rolling redeployment)

Hosts

Tool	Parameters	Description
host_list	tenant_id	List all hosts (VMs) in a tenant
host_get	tenant_id, name	Get details of a specific host
host_create	tenant_id, friendly_name, capacity, agent_platform=0	Create a new host (0=Linux Docker, 7=EKS Linux)
host_delete	tenant_id, name	Terminate a host
host_reboot	tenant_id, name	Reboot a host

Databases

Tool	Parameters	Description
database_list	tenant_id	List all RDS instances in a tenant
database_get	tenant_id, name	Get details of an RDS instance
database_create	tenant_id, identifier, engine, size, master_username="master", master_password?	Create an RDS instance
database_update	tenant_id, name, size?	Resize an RDS instance
database_delete	tenant_id, name	Delete an RDS instance

Storage

Tool	Parameters	Description
bucket_list	tenant_id	List all S3 buckets in a tenant
bucket_get	tenant_id, name	Get details of an S3 bucket
bucket_create	tenant_id, name	Create a new S3 bucket
bucket_update	tenant_id, name, versioning?	Update bucket configuration (versioning)
bucket_delete	tenant_id, name	Delete an S3 bucket

Containers (ECS)

Tool	Parameters	Description
ecs_service_list	tenant_id	List all ECS services in a tenant
ecs_task_def_list	tenant_id	List all ECS task definition families
ecs_task_list	tenant_id, service_name	List running tasks for a service
ecs_task_run	tenant_id, family_name, replicas=1	Run a task from a task definition family
ecs_service_update	tenant_id, name, image	Update the image of an ECS service
ecs_service_delete	tenant_id, name	Delete an ECS service

Troubleshooting

Missing environment variables

DuploError: DUPLO_HOST environment variable is required

Set DUPLO_HOST and DUPLO_TOKEN before running. See .env.example.

Invalid or expired token

{"error": "Unauthorized", "code": 401}

Generate a new API token from the DuploCloud portal: User menu > Security > API Token.

Tenant not found

{"error": "Tenant 'xyz' not found", "code": 404}

Verify the tenant name with tenant_list. Tenant names are case-sensitive.

Connection refused

{"error": "Unexpected error: Connection refused", "code": 500}

Verify DUPLO_HOST is correct and the DuploCloud portal is reachable from your network.

Development

# Install with dev dependencies
uv sync

# Lint & format
uv run ruff check .
uv run ruff format .

# Tests
uv run pytest
uv run pytest --cov=duplocloud_mcp --cov-report=term-missing

# Single test
uv run pytest tests/test_tools/test_services.py::test_service_list

Architecture

main.py                          # Entrypoint: mcp.run(transport="stdio")
duplocloud_mcp/
  server.py                      # FastMCP instance, imports tool modules
  client.py                      # DuploClient singleton wrapper
  errors.py                      # Error decorator, validators
  tools/
    tenants.py                   # Tenant CRUD tools
    services.py                  # Service CRUD + restart tools
    hosts.py                     # Host CRUD + reboot tools
    databases.py                 # RDS database CRUD tools
    storage.py                   # S3 bucket CRUD tools
    containers.py                # ECS service/task tools

Each tool module imports the shared mcp instance from server.py and registers tools via @mcp.tool(). The @handle_duplo_errors decorator translates DuploCloud exceptions into structured JSON error responses. The duplocloud-client library handles all REST API communication.

License

MIT