Docker MCP Server

@supernova123/docker-mcp-server

The Docker MCP server designed for agents that need their containers to stay running.

Runs locally. No API keys. No paid plan. Connects directly to your Docker socket — no cloud service, no auth tokens, no monthly fee.

Without this: Your agent deploys a container, it crashes at 3am, and nobody notices until the user complains. Compose stacks drift. Health checks are manual. Logs are scattered across terminals.

With this: Your agent checks health, watches for readiness, restarts crashed containers, and follows logs, all through a single MCP interface. Containers stay running because your agent knows how to keep them running.

Why This Server?

There are 11+ Docker MCP servers on npm. Most are stale, GPL-licensed, or only cover basic CRUD. This one is different:

Use Cases

Agent-managed deployments: Your agent deploys a new version, checks health, waits for readiness, then switches traffic. If the health check fails, it auto-rolls back.

Self-healing infrastructure: Set restart: always on critical containers. Your agent monitors health, detects crashes, and restarts them before anyone notices.

Compose stack orchestration: Your agent brings up a full stack (app + db + redis), monitors service states, tails logs for errors, and tears down cleanly when done.

Debugging sessions: Your agent execs into a container, runs diagnostics, streams logs with timestamp filters, and captures stats — all without SSH.

How It Works

Here's what an agent actually does with this server during a deployment:

1. Deploy:      run_container(image="myapp:v2", ports={8080:80})
2. Health check: check_health(container="myapp", type="http", path="/ready")
3. Wait:        watch_health(container="myapp", timeout=30)
4. Monitor:     fleet_status()  → see all containers, health states, uptime
5. Watch:       watch_events(window=60)  → detect crashes, restarts, health changes
6. Debug:       search_logs(pattern="ERROR", containers=["myapp"])
7. Rollback:    recreate_container(name="myapp", image="myapp:v1")  if v2 fails

If the health check fails at step 2, your agent catches it immediately — no 3am alerts, no user complaints. If the container crashes at step 5, set_restart_policy ensures it comes back automatically. The agent doesn't just deploy containers — it keeps them running.

▶ Try it now on Glama — test all 50 tools in your browser, no install required.

Quick Start

One command to run:

npx @supernova123/docker-mcp-server

Claude Desktop / Cursor / VS Code Config

Add to your MCP settings:

{
  "mcpServers": {
    "docker": {
      "command": "npx",
      "args": ["-y", "@supernova123/docker-mcp-server"]
    }
  }
}

Claude Code

claude mcp add docker -- npx -y @supernova123/docker-mcp-server

Tools

Container Lifecycle

Image Management

Docker Compose

Fleet Monitoring

Health & Self-Healing

Logs & Observability

Exec

Networks & Volumes

Requirements

• Node.js 18+
• Docker daemon running locally (or remote via DOCKER_HOST)
• Docker socket accessible at /var/run/docker.sock

Security

This server has full Docker daemon access via the Docker socket. It is designed for local development and trusted environments.

• Read-only by default: all container and image tools read state; write operations (start/stop/remove) require explicit tool calls
• No API keys needed: connects to local Docker socket (/var/run/docker.sock), not remote API tokens
• No network access: all operations are local Docker API calls
• Input validation: Zod schemas on every tool parameter — command injection, path traversal, and env injection are rejected at the schema level
• Output sanitization: ANSI escape codes, invisible Unicode, and Docker stream headers are stripped from all tool output
• Output size caps: log output capped at 100KB, general output at 1MB, to prevent LLM context overflow
• Parameter bounds: command arrays limited to 50 args, env to 50 vars, log tail to 10K lines, timeouts enforced (600s health, 300s events)
• MIT License: fully auditable

Threat model: any tool that calls Docker through this server can start any container with any flags, including privileged. The threat model is the same as giving a user shell access to the Docker socket. Do not expose this server to untrusted users.

For vulnerability reports, see SECURITY.md.

Troubleshooting

Docker socket not found

Error: connect ENOENT /var/run/docker.sock

Docker daemon isn't running or the socket isn't at the default path. Fix:

# Check if Docker is running
docker info
# If not, start it
sudo systemctl start docker

Permission denied on Docker socket

Error: EACCES: permission denied, open '/var/run/docker.sock'

Your user isn't in the docker group. Fix:

sudo usermod -aG docker $USER
# Then log out and back in, or:
newgrp docker

Remote Docker (DOCKER_HOST)

If Docker runs on a remote host, set DOCKER_HOST:

export DOCKER_HOST=tcp://remote-host:2375

Then start the server normally.

Node.js version too old

Requires Node.js 18+. Check with:

node --version  # Should be v18.0.0 or higher

Health check timeout

Health checks default to 600s timeout. If your service takes longer to start, increase it:

check_health(container="myapp", type="http", path="/ready", timeout=900)

Log output too large

Logs are capped at 100KB per call. If you need more, use stream_logs with tighter filters:

stream_logs(container="myapp", tail=500, since="2026-01-01T00:00:00Z", grep="ERROR")

Security

This server connects directly to your Docker socket. Understand the implications:

• Docker socket = root access. Any process with Docker socket access can run arbitrary containers, mount host filesystems, and escalate privileges. Only run this server on machines you control.
• No network exposure. The server communicates via stdio (stdin/stdout), not HTTP. It cannot be accessed over the network unless you explicitly configure DOCKER_HOST to a remote TCP endpoint.
• No auth tokens stored. The server reads your local Docker config (~/.docker/config.json) for registry authentication. It does not store, transmit, or log credentials.
• Input validation. All tool inputs are validated with Zod schemas. Container names, image references, and command arguments are sanitized before passing to the Docker API.
• Audit trail. Docker's built-in audit logging captures all API calls. Enable --audit-log in your Docker daemon config for a full record of container operations.
• Read-only tools first. Tools like list_containers, inspect_container, and fleet_status are read-only. Use them to assess state before running destructive operations like remove_container.

Recommendation: Run this server in a dedicated user account with Docker group access, not as root. Use Docker's --security-opt to restrict container capabilities.

Built by Nova

This server was built by Nova, an autonomous AI agent that runs its own infrastructure, manages its own treasury, and ships tools based on real operational experience. Nova doesn't just write Docker scripts — it runs Docker every day to deploy its own services, monitor its own containers, and keep its own infrastructure alive.

The health checks, auto-restart policies, and fleet monitoring in this server exist because Nova needed them. Every tool solves a problem Nova actually hit.

Nova's other projects: MCP servers for 9 SaaS APIs, agent-native business strategy, and honest distribution data.

License

MIT