docker-k8s-mcp

MCP server for managing Docker and Kubernetes from Claude Desktop, Cursor, or any MCP-compatible client.

Tools

Docker

| Tool | Description | |---|---| | list_containers | List running (or all) containers with status and ports | | get_container_logs | Fetch stdout/stderr logs for the last N minutes (up to 10 MB) | | get_container_stats | CPU %, memory, network I/O, block I/O snapshot | | restart_container | Restart with a 10-second grace period | | inspect_container | Image, ports, mounts, env vars (secrets redacted) |

Kubernetes

| Tool | Description | |---|---| | list_pods | List pods with phase, readiness, restart count, age | | get_pod_logs | Last N lines from a pod or specific container (up to 10 MB) | | describe_pod | Status, conditions, events - useful for CrashLoopBackOff/OOMKilled | | restart_deployment | Rolling restart via annotation patch | | get_pod_resources | Live CPU/memory per container (requires metrics-server) |

All tool calls have a 30-second timeout (60 seconds for log fetching).

Requirements

• Go 1.21+
• Docker daemon running locally (or remote via DOCKER_HOST)
• kubectl configured with a valid kubeconfig

Build

go build -o docker-k8s-mcp .

Move to a stable path:

mv docker-k8s-mcp /usr/local/bin/docker-k8s-mcp

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "docker-k8s": {
      "command": "/usr/local/bin/docker-k8s-mcp"
    }
  }
}

Restart Claude Desktop. A hammer icon will appear at the bottom of the chat window. Click it to confirm the 10 tools are listed.

Cursor

Edit ~/.cursor/mcp.json (create if missing):

{
  "mcpServers": {
    "docker-k8s": {
      "command": "/usr/local/bin/docker-k8s-mcp"
    }
  }
}

VS Code

Edit .vscode/mcp.json in your workspace:

{
  "servers": {
    "docker-k8s": {
      "type": "stdio",
      "command": "/usr/local/bin/docker-k8s-mcp"
    }
  }
}

Environment variables

| Variable | Default | Description | |---|---|---| | DOCKER_HOST | unix:///var/run/docker.sock | Docker daemon socket | | KUBECONFIG | ~/.kube/config | Kubeconfig path | | LOG_LEVEL | info | debug, info, warn, error |

If Docker or Kubernetes is unavailable at startup, the server still starts. Tools for the unavailable backend will return an error message explaining what is missing.

Remote Docker

To connect to a Docker daemon running on another machine, set DOCKER_HOST in the MCP config:

{
  "mcpServers": {
    "docker-k8s": {
      "command": "/usr/local/bin/docker-k8s-mcp",
      "env": {
        "DOCKER_HOST": "tcp://192.168.1.10:2376",
        "DOCKER_TLS_VERIFY": "1",
        "DOCKER_CERT_PATH": "/Users/you/.docker/certs/my-server"
      }
    }
  }
}

DOCKER_CERT_PATH should point to a directory containing ca.pem, cert.pem, and key.pem. These are the client certificates generated when you set up TLS on the remote daemon.

If TLS is not configured on the remote daemon (e.g. in a trusted internal network), use port 2375 and omit the TLS variables:

"DOCKER_HOST": "tcp://192.168.1.10:2375"

Via SSH tunnel (no certificates needed):

ssh -NL 2375:localhost:2375 user@remote-host

Then set DOCKER_HOST=tcp://localhost:2375.

Running in Docker

FROM golang:1.23-alpine AS builder
WORKDIR /app
COPY . .
RUN go build -o docker-k8s-mcp .

FROM alpine:3.20
COPY --from=builder /app/docker-k8s-mcp /usr/local/bin/
CMD ["docker-k8s-mcp"]

docker run --rm -i \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ~/.kube:/root/.kube:ro \
  docker-k8s-mcp

Example prompts

Show me all running Docker containers and their memory usage.

The payment-service pod is crashing. Describe it and fetch the last 200 log lines.

Restart the api-gateway deployment in the production namespace.

Which pods in the staging namespace have more than 5 restarts?

Project structure

main.go                   - server init, signal handling, graceful shutdown
tools/docker.go           - Docker tool definitions and handlers
tools/k8s.go              - Kubernetes tool definitions and handlers
internal/docker/client.go - Docker SDK client
internal/docker/tools.go  - Docker logic
internal/k8s/client.go    - Kubernetes client (in-cluster + kubeconfig)
internal/k8s/tools.go     - Kubernetes logic

Transport: stdio (JSON-RPC 2.0 over stdin/stdout).