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
MCP server for Komodo Docker/container management
星數
4
工具
—
可用率
—
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):
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
Open the Komodo web UI
Go to Settings → API Keys
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 and 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.
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)
The server uses the official komodo_client 2.1.1 package for the Komodo Core API. It sends JSON POST requests to /read/<Operation>, /write/<Operation>, or /execute/<Operation>, with the operation parameters as the request body and API-key headers:
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.
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.