Set Up Docker MCP Server for Claude Code
A Docker MCP server lets Claude Code manage containers, inspect images, read logs, and orchestrate compose stacks directly. Instead of copying and pasting Docker CLI output, Claude can query container status, tail logs, and restart services through structured MCP tool calls.
The Problem
When debugging containerized applications, you constantly switch between Claude Code and the terminal to check container status, read logs, and restart services. Claude cannot see your Docker environment – it suggests commands but cannot verify whether they worked. This back-and-forth wastes time and introduces copy-paste errors.
Quick Solution
- Install the Docker MCP server:
npm install -g @anthropic/docker-mcp-server
- Configure it in your project
.mcp.json:
{
"mcpServers": {
"docker": {
"command": "docker-mcp-server",
"args": [],
"env": {
"DOCKER_HOST": "unix:///var/run/docker.sock"
}
}
}
}
- Verify the connection:
claude mcp list
# Should show "docker" as connected
- Use Docker tools in your Claude session:
claude "List all running containers. Show me the logs
from the api container for the last 5 minutes. If there
are any errors, diagnose the root cause."
- Manage compose stacks:
claude "Read docker-compose.yml and start all services.
Wait for health checks to pass on the db and redis
services before confirming the stack is ready."
How It Works
The Docker MCP server connects to the Docker daemon via the Docker socket (/var/run/docker.sock) and exposes container management tools through the MCP protocol. Claude Code spawns it as a child process and communicates via stdio transport.
Typical tools exposed include:
- list_containers – lists running and stopped containers with status, ports, and names
- container_logs – retrieves logs from a specific container with time filtering
- exec_container – runs a command inside a running container
- inspect_container – returns detailed container metadata, environment, and network config
- compose_up/down – manages Docker Compose stacks
- list_images – shows local Docker images with sizes and tags
When Claude investigates a containerized application issue, it calls list_containers to see the state of all services, then container_logs on the failing service to read the error output. It can then exec_container to run diagnostic commands inside the container (checking network connectivity, file permissions, or process state) without you leaving the Claude Code session.
This creates a closed debugging loop: Claude reads the code, checks the container state, reads the logs, makes a code change, rebuilds the container, and verifies the fix – all within a single conversation.
Common Issues
Docker socket permission denied. The MCP server needs access to /var/run/docker.sock. On Linux, the user running Claude Code must be in the docker group. On macOS with Docker Desktop, this is handled automatically:
# Linux: add your user to the docker group
sudo usermod -aG docker $USER
# Then log out and back in
Container names vary between environments. Docker Compose prefixes container names with the project directory name. Use the --project-name flag or set it in .env to ensure consistent names:
# docker-compose.yml
name: myproject
services:
api:
build: .
MCP server cannot see remote Docker hosts. The Docker MCP server connects to the local Docker daemon by default. For remote hosts, set the DOCKER_HOST environment variable in the MCP config:
{
"env": {
"DOCKER_HOST": "tcp://remote-host:2376",
"DOCKER_TLS_VERIFY": "1",
"DOCKER_CERT_PATH": "/path/to/certs"
}
}
Example CLAUDE.md Section
# Docker MCP Server
## Available Tools
- `list_containers`: Show all containers and status
- `container_logs`: Read container logs (use --since for time filter)
- `exec_container`: Run commands inside containers
- `compose_up`: Start Docker Compose stack
- `compose_down`: Stop Docker Compose stack
## Project Services (docker-compose.yml)
- api: Node.js Express API (port 3000)
- db: PostgreSQL 15 (port 5432)
- redis: Redis 7 (port 6379)
- worker: Background job processor
## Debugging Workflow
1. Check container status: list_containers
2. Read logs from failing service: container_logs
3. Verify networking: exec_container with curl/ping
4. Fix code, rebuild: docker compose up --build api
5. Verify fix via container_logs
## Safety Rules
- NEVER run exec_container on production containers
- ALWAYS use --since flag for logs (avoid massive output)
- Rebuild only the changed service, not the full stack
Best Practices
- Use the
--sinceflag for container logs. Without time filtering, Claude receives the entire log history which may overflow the context window. Filter to the last 5-10 minutes for debugging. - Set a consistent project name in docker-compose.yml to ensure container names are predictable across environments. Claude needs consistent names to reference containers reliably.
- Add the Docker MCP to project-level config (
.mcp.json) rather than global config. Different projects have different compose stacks and the MCP server should connect to the right Docker context. - Document your service architecture in CLAUDE.md. List each service, its port, its health check endpoint, and common failure patterns so Claude has context before querying containers.
- Never expose the Docker socket to production MCP servers. The Docker socket provides root-level access to the host. Use it only in development environments.
Related Reading
- Claude Code MCP Server Setup
- Claude Code Docker Compose Development Workflow
- Claude Code Docker Build Failed Fix
Built by theluckystrike. More at zovo.one