docker-mcp

A read-only MCP server for Docker. Exposes your Docker daemon over the Model Context Protocol so AI assistants can inspect containers and logs without any write access.

Built with FastAPI and FastMCP.

Tools

Tool	Description
`list_containers`	List running containers (pass `all=true` to include stopped)
`get_container`	Full details for a container — ports, networks, env vars, mounts, resource limits
`get_logs`	Fetch container logs with filtering by tail/head, time range, and regex pattern

`get_logs` parameters

Parameter	Default	Description
`container_id`	—	Container ID or name
`tail`	`100`	Last N lines. Mutually exclusive with `head`.
`head`	—	First N lines. Mutually exclusive with `tail`.
`since`	—	UTC datetime — only return logs after this time
`until`	—	UTC datetime — only return logs before this time
`last_minutes`	—	Convenience shorthand: logs from the last N minutes
`pattern`	—	Regex (or substring) filter applied to log lines
`timestamps`	`true`	Prefix each line with an RFC3339 timestamp

Quick start

Docker run

docker run -d \
  --name docker-mcp \
  -p 8000:8000 \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -e MCP_API_KEY=mysecret \
  codeberg.org/jhot/docker-mcp:latest

Docker Compose

services:
  docker-mcp:
    image: codeberg.org/jhot/docker-mcp:latest
    ports:
      - "8000:8000"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      MCP_API_KEY: ${MCP_API_KEY:-}
    restart: unless-stopped

MCP_API_KEY=mysecret docker compose up -d

Configuration

Variable	Default	Description
`MCP_API_KEY`	unset	Bearer token for `/mcp`. Unset = no auth.
`DOCKER_HOST`	unset	Docker daemon socket. Unset = `/var/run/docker.sock`.
`HOST`	`0.0.0.0`	Uvicorn bind address
`PORT`	`8000`	Host port (container always listens on 8000)
`LOG_LEVEL`	`info`	Uvicorn log level

MCP endpoint

The MCP Streamable HTTP endpoint is at http://localhost:8000/mcp.

Configure your client (e.g. Claude Desktop, Cursor) to connect to it:

{
  "mcpServers": {
    "docker": {
      "url": "http://localhost:8000/mcp",
      "headers": {
        "Authorization": "Bearer mysecret"
      }
    }
  }
}

Omit headers if MCP_API_KEY is not set.

Security

The Docker socket grants full control of the Docker daemon. Treat access to this server the same as access to the socket itself:

Set MCP_API_KEY for any network-accessible deployment.
Use a firewall or reverse proxy to restrict which clients can reach port 8000.
The :ro socket mount prevents replacing the socket file but does not restrict Docker API calls — MCP_API_KEY is the primary access control.

Remote Docker

To connect to a remote Docker daemon instead of the local socket, remove the volumes block and set DOCKER_HOST:

docker run -d \
  --name docker-mcp \
  -p 8000:8000 \
  -e DOCKER_HOST=tcp://192.168.1.10:2376 \
  -e MCP_API_KEY=mysecret \
  codeberg.org/jhot/docker-mcp:latest

Routes

Path	Auth	Description
`/`	public	Landing page
`/health`	public	`{"status": "ok"}`
`/api/tools`	public	Tool metadata list
`/mcp`	gated	FastMCP Streamable HTTP endpoint

Development

Requirements: mise, Python 3.12, Docker

mise exec -- task install   # uv sync
mise exec -- task fmt        # ruff format
mise exec -- task lint       # ruff check
mise exec -- task test       # unit tests (no Docker required)
mise exec -- task test-integration  # integration tests (requires live Docker)
mise exec -- task run        # dev server at http://localhost:8000
mise exec -- task build      # docker build
mise exec -- task up         # docker compose up --build

docker-mcp

docker-mcp

Tools

`get_logs` parameters

Quick start

Docker run

Docker Compose

Configuration

MCP endpoint

Security

Remote Docker

Routes

Development

Latest Blog Posts

MCP directory API

docker-mcp

Tools

get_logs parameters

Quick start

Docker run

Docker Compose

Configuration

MCP endpoint

Security

Remote Docker

Routes

Development

Latest Blog Posts

MCP directory API

`get_logs` parameters