Docker MCP Server

MCP Server Configuration

Add to .claude/settings.json:

Copy
{
  "mcpServers": {
    "docker": {
      "command": "npx",
      "args": ["-y", "@docker/mcp-server-docker"],
      "env": {
        "DOCKER_HOST": "unix:///var/run/docker.sock"
      }
    }
  }
}

Available Tools

Tool	Description
list-containers	List running (or all) containers with status
inspect-container	Get detailed info about a container (ports, volumes, env)
container-logs	Retrieve stdout/stderr logs from a container
run-container	Start a new container from an image
stop-container	Stop a running container
remove-container	Remove a stopped container
list-images	List available Docker images
build-image	Build an image from a Dockerfile
compose-up	Start services defined in docker-compose.yml
compose-down	Stop and remove compose services
compose-logs	View logs from compose services

Common Workflows

Debug a Failing Container

1. list-containers (--all to include stopped)
2. container-logs (tail last 100 lines)
3. inspect-container (check env vars, port mappings, health status)
4. Identify the issue and suggest a fix

Development Environment Setup

1. compose-up (start all services: db, cache, api)
2. list-containers (verify all services are healthy)
3. container-logs for any unhealthy service
4. Run tests against the containerized services

Dockerfile Best Practices

Copy
# Multi-stage build for minimal production image
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production && npm cache clean --force
COPY . .
RUN npm run build

FROM node:20-alpine AS production
WORKDIR /app

# Security: run as non-root user
RUN addgroup -g 1001 appgroup && \
    adduser -u 1001 -G appgroup -s /bin/sh -D appuser

COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./

USER appuser
EXPOSE 3000

HEALTHCHECK --interval=30s --timeout=3s --retries=3 \
  CMD wget -qO- http://localhost:3000/health || exit 1

CMD ["node", "dist/server.js"]

Docker Compose Template

Copy
version: '3.8'

services:
  api:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=postgresql://user:pass@db:5432/myapp
      - REDIS_URL=redis://cache:6379
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_started
    restart: unless-stopped

  db:
    image: postgres:16-alpine
    volumes:
      - pgdata:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: myapp
      POSTGRES_USER: user
      POSTGRES_PASSWORD: pass
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U user -d myapp"]
      interval: 5s
      timeout: 3s
      retries: 5

  cache:
    image: redis:7-alpine
    command: redis-server --maxmemory 256mb --maxmemory-policy allkeys-lru

volumes:
  pgdata:

Setup

1. Ensure Docker Desktop or Docker Engine is running
2. Verify Docker socket is accessible: docker ps
3. Add the MCP configuration to .claude/settings.json
4. For remote Docker hosts, update DOCKER_HOST to point to the remote socket

Security Notes

• The Docker socket grants full control over Docker -- equivalent to root access on the host
• Consider using Docker contexts for remote hosts instead of exposing the socket
• Never run untrusted images without reviewing them first
• Use --read-only and --no-new-privileges flags for production containers
• Scan images for vulnerabilities: docker scout cves <image>
• The MCP server has the same permissions as your Docker CLI user