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