Komodo Mcp

Komodo MCP Server

An MCP (Model Context Protocol) server that exposes Komodo — a Docker/container management and deployment system — to AI assistants.

Highlights

• 35 tools across read / execute / write categories
• Streamable HTTP transport (default) per the latest MCP spec, plus legacy SSE and stdio
• Per-session McpServer — concurrent clients are isolated
• Official komodo_client 2.1.1 for the upstream API contract
• Bearer-token auth with constant-time compare; loopback-only fallback when no token is configured
• DNS-rebinding defense via a default Host allow-list and an optional Origin allow-list
• Helmet security headers; CORS allow-list
• Pino structured logs with Authorization/X-Api-Secret/X-Api-Key redaction
• Graceful shutdown on SIGTERM/SIGINT
• Strict input schemas: bounded tail, terms, compose_contents, and contents; update configs reject keys beginning with API-key, API-secret, password, secret, webhook-secret, or token variants
• Shared upstream adapter with Undici pooling, an absolute timeout, a 16 MiB response cap, p-limit concurrency control, and secret redaction; requests are not retried

Quick Start

Local (loopback) with Docker Compose

git clone https://github.com/nicolasestrem/komodo-mcp.git
cd komodo-mcp
export KOMODO_ADDRESS=http://host.docker.internal:9120
export KOMODO_API_KEY='YOUR_KEY'
export KOMODO_API_SECRET='YOUR_SECRET'
export MCP_AUTH_TOKEN="$(openssl rand -hex 32)"
docker compose up -d

Plain docker compose automatically loads the local-development override and passes these environment variables into the container. The container binds 0.0.0.0:3113 internally but docker-compose.yml publishes the port only to host loopback (127.0.0.1:3113:3113). Docker requests still cross a container-network boundary, so use the generated bearer token. Front the service with a reverse proxy when you need network access.

Add to Claude Code (.mcp.json)

Local npm process / loopback (no token needed when MCP_AUTH_TOKEN is unset):

{
  "mcpServers": {
    "komodo": {
      "type": "http",
      "url": "http://127.0.0.1:3113/mcp"
    }
  }
}

Docker (token required):

{
  "mcpServers": {
    "komodo": {
      "type": "http",
      "url": "http://127.0.0.1:3113/mcp",
      "headers": { "Authorization": "Bearer ${MCP_AUTH_TOKEN}" }
    }
  }
}

For a networked deployment, replace the URL with the TLS endpoint exposed by your reverse proxy.

Local development (npm)

npm install
npm run build
npm start         # default streamable HTTP on 127.0.0.1:3113
npm run dev:sse   # legacy SSE transport with a dev token

Configuration

Komodo upstream

| Variable | Description | Default | |---|---|---| | KOMODO_ADDRESS | Komodo Core URL (http(s) only; trailing slash normalized); also reads from KOMODO_ADDRESS_FILE | required | | KOMODO_API_KEY | API key — also reads from KOMODO_API_KEY_FILE for Docker secrets | required | | KOMODO_API_SECRET | API secret — also reads from KOMODO_API_SECRET_FILE | required | | KOMODO_TIMEOUT_MS | Absolute per-request timeout | 30000 | | KOMODO_MAX_CONCURRENCY | In-flight request semaphore | 8 | | KOMODO_MAX_RESPONSE_BYTES | Maximum upstream response body size | 16777216 (16 MiB) |

MCP server

| Variable | Description | Default | |---|---|---| | MCP_TRANSPORT | streamable (default), sse (legacy), or stdio | streamable | | MCP_PORT | HTTP listener port | 3113 | | MCP_BIND_HOST | Host to bind on | 127.0.0.1 (use 0.0.0.0 inside Docker) | | MCP_AUTH_TOKEN | Bearer token (also MCP_AUTH_TOKEN_FILE). When unset, only loopback callers are admitted. | unset | | MCP_ALLOWED_ORIGINS | Comma-separated Origin allow-list (browser CSRF defense). Empty = no Origin enforcement. | unset | | MCP_ALLOWED_HOSTS | Comma-separated Host-header allow-list (DNS-rebinding defense). | 127.0.0.1,localhost | | MCP_MAX_SESSIONS | Maximum simultaneous HTTP sessions; invalid values fall back to the default | 100 | | MCP_SESSION_IDLE_TIMEOUT_MS | Idle lifetime for HTTP sessions before cleanup | 1800000 (30 minutes) | | LOG_LEVEL | Pino log level | info |

Getting Komodo API credentials

1. Open the Komodo web UI
2. Go to Settings → API Keys
3. Click Create API Key, copy the key and secret

Security model

This server holds Komodo admin credentials. A successful tool call can deploy code, prune systems, or destroy stacks on every Komodo-managed host. Treat it as privileged.

The defaults aim for "secure by accident":

• Bind is 127.0.0.1 unless explicitly opened.
• MCP_AUTH_TOKEN is required for any non-loopback caller.
• The default Host allow-list blocks DNS rebinding even if a browser is tricked into reaching the loopback port; MCP_ALLOWED_ORIGINS adds optional browser Origin enforcement.
• All requests, including loopback, go through Helmet + CORS.
• Errors emitted to MCP clients have the API key/secret scrubbed from upstream bodies.

For non-loopback deployments use a reverse proxy that terminates TLS, set a random MCP_AUTH_TOKEN (openssl rand -hex 32), and configure MCP_ALLOWED_HOSTS/MCP_ALLOWED_ORIGINS for your domain. See [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) and [docs/RUNBOOK.md](docs/RUNBOOK.md).

Available tools

35 tools are registered from a single declarative table in src/tools/registry.ts. Read tools carry readOnlyHint and idempotentHint; start/stop/restart and pull operations carry idempotentHint; prune/destroy/delete and komodo_write_stack_contents carry destructiveHint. Exact operation mappings and schemas are in [docs/API.md](docs/API.md).

Read (15)

| Tool | Description | |---|---| | komodo_list_servers | List all connected servers | | komodo_list_stacks | List stacks with state | | komodo_list_deployments | List deployments | | komodo_get_stack | Stack details | | komodo_get_stack_log | Stack deployment logs | | komodo_get_container_log | Container logs (tail 1–5000, default 100) | | komodo_list_containers | Containers on a server | | komodo_inspect_container | Inspect a container | | komodo_get_system_stats | CPU/memory/disk for a server | | komodo_list_images | Docker images | | komodo_list_networks | Docker networks | | komodo_list_volumes | Docker volumes | | komodo_get_alerts | Komodo alerts | | komodo_search_logs | Search container logs (1–20 terms, max 256 chars each) | | komodo_get_stack_services | Stack services summary (requires stack) |

Execute (12)

| Tool | Hint | Description | |---|---|---| | komodo_deploy_stack | non-idempotent | Deploy/redeploy a stack | | komodo_start_stack | idempotent | Start a stopped stack | | komodo_stop_stack | idempotent | Stop a running stack | | komodo_restart_stack | idempotent | Restart a stack | | komodo_destroy_stack | destructive | Stop and remove | | komodo_pull_stack | idempotent | Pull latest images | | komodo_start_container | idempotent | Start a container | | komodo_stop_container | idempotent | Stop a container | | komodo_restart_container | idempotent | Restart a container | | komodo_prune_images | destructive | Prune unused images | | komodo_prune_networks | destructive | Prune unused networks | | komodo_prune_system | destructive | Full Docker system prune |

Write (8)

| Tool | Hint | Description | |---|---|---| | komodo_create_stack | non-idempotent | Create a stack | | komodo_update_stack | non-idempotent | Update stack config (rejects secret-like keys) | | komodo_delete_stack | destructive | Delete a stack | | komodo_write_stack_contents | destructive | Overwrite compose contents; requires stack, file_path, and contents (max string length 256,000) | | komodo_create_server | non-idempotent | Add a server | | komodo_update_server | non-idempotent | Update server config (rejects secret-like keys) | | komodo_delete_server | destructive | Remove a server | | komodo_rename_stack | non-idempotent | Rename a stack |

Example prompts

• "List all my Komodo stacks"
• "Show me the logs for the nginx stack"
• "Restart the wordpress stack"
• "What containers are running on my server?"
• "Deploy the staging stack"

Development

npm install
npm run lint     # biome
npm run build    # tsc
npm test         # node:test suites (auth/secret/tool/format/smoke)
npm run dev      # tsc --watch

Architecture

src/
├── index.ts            # Express factory, transports, auth/Origin/Host gates, SIGTERM
├── server.ts           # createServer({ client? }) — DI-friendly factory
├── komodo-client.ts    # Official client adapter: shared Undici pool, timeout/size/concurrency guards
└── tools/
    ├── registry.ts     # Declarative TOOLS table + registerAll(server, client)
    └── utils.ts        # formatResult + toolHandler (errors → MCP isError)

See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for diagrams and the request-flow walk-through.

API reference

The server uses the official komodo_client 2.1.1 package for the Komodo Core API. It sends JSON POST requests to /read/, /write/, or /execute/, with the operation parameters as the request body and API-key headers:

curl -X POST http://your-komodo:9120/read/ListStacks \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_KEY" \
  -H "X-Api-Secret: YOUR_SECRET" \
  -d '{}'

Streamable HTTP and legacy SSE each create a separate McpServer per session while sharing one upstream adapter. Idle sessions are closed after MCP_SESSION_IDLE_TIMEOUT_MS; requests carrying an unknown session ID receive HTTP 404. CORS exposes the mcp-session-id response header to allowed browser clients.

License

MIT — see [LICENSE](LICENSE).

Dependency note: the official komodo_client package declares GPL-3.0. Redistribution scenarios should receive a separate licensing review; this note is not a legal conclusion.

Links

• Komodo documentation
• Komodo GitHub
• MCP protocol

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: nicolasestrem
• Source: nicolasestrem/komodo-mcp
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.