# docker-mcp

MCP (Model Context Protocol) server wrapping the Docker Engine API. Exposes Docker operations as typed MCP tools, reducing token consumption versus generating CLI commands.

## Quick Start

```bash
npx docker-mcp
```

Or add to your MCP client config (OpenCode, Claude Desktop, etc.):

```json
{
  "mcpServers": {
    "docker": {
      "command": "npx",
      "args": ["docker-mcp"]
    }
  }
}
```

## Configuration

Configure via environment variables, matching Docker CLI conventions:

| Variable | Purpose | Example |
|---|---|---|
| `DOCKER_HOST` | Docker daemon address | `ssh://user@192.168.1.111` |
| `DOCKER_TLS_VERIFY` | Enable TLS | `1` |
| `DOCKER_CERT_PATH` | TLS cert directory | `~/.docker/certs` |

**Default**: Connects to local Docker socket (`/var/run/docker.sock`).

### Connection methods (recommended order)

1. **SSH** (preferred): `DOCKER_HOST=ssh://user@host` — dockerode handles SSH natively. Pre-populate `~/.ssh/known_hosts` to avoid host key prompts.
2. **TCP + TLS**: `DOCKER_HOST=tcp://host:2376` with `DOCKER_TLS_VERIFY=1` and `DOCKER_CERT_PATH`.
3. **Plain TCP**: `DOCKER_HOST=tcp://host:2375` — **warning**: unencrypted TCP grants root access to anyone on the network. Only use on trusted LANs.

### Authentication

For private registries, prefer pre-configuring credentials:

```bash
docker login myregistry.io
```

dockerode reads `~/.docker/config.json` automatically. Inline `auth` parameters are also supported on `image_action` pull/push, but note that credentials transit the MCP protocol (stdin/stdout).

## Tools (17 total)

### Container tools
| Tool | Description |
|---|---|
| `container_query` | List or inspect containers. Supports filters (status, label), limit, field selection, verbose mode. |
| `container_action` | Start, stop, restart, pause, unpause, or remove containers. |
| `container_create` | Create a container from an image with env, ports, volumes. |
| `container_logs` | Get container logs with tail limit (default 100, max 10,000) and timestamps. ANSI codes stripped. |
| `container_exec` | Run a command inside a running container. Output capped at 10KB/200 lines. |

### Image tools
| Tool | Description |
|---|---|
| `image_query` | List or inspect images. Supports dangling filter, field selection. |
| `image_action` | Pull, remove, tag, or push images. Supports registry auth. |
| `image_build` | Build an image from a Dockerfile. |

### Volume tools
| Tool | Description |
|---|---|
| `volume_query` | List or inspect volumes. |
| `volume_action` | Create or remove volumes. |

### Network tools
| Tool | Description |
|---|---|
| `network_query` | List or inspect networks. |
| `network_action` | Create, remove, connect, or disconnect networks. |

### Compose tools
| Tool | Description |
|---|---|
| `compose_action` | Up, down, pull, or stop Compose projects. Fire-and-forget for up (check with `compose_query ps`). |
| `compose_query` | List services (ps), validate config, or get logs. |

### System tools
| Tool | Description |
|---|---|
| `system_df` | Docker disk usage breakdown. |
| `system_prune` | Prune unused resources by scope (all, containers, images, volumes, networks, builder). |

### Health
| Tool | Description |
|---|---|
| `docker_ping` | Check Docker daemon connectivity and return version info. |

## Token Optimization

This server is designed to minimize token consumption:

- **Default summaries**: Query tools return curated fields by default. Use `verbose: true` for full payloads.
- **Field selection**: Pass `fields: ["Id", "State.Status"]` to get only the data you need.
- **Pagination**: Use `limit` on list tools to cap result size.
- **Log capping**: Logs default to 100 lines (max 10,000). Exec output capped at 10KB/200 lines.
- **Compact IDs**: 12-character IDs by default. Use `fullId: true` for full 64-char IDs.
- **ANSI stripping**: All output has ANSI codes stripped server-side.
- **Tool consolidation**: Related operations merged into 17 tools via action enums instead of 35 individual tools.

## Security Notes

- `container_exec` allows arbitrary command execution in any container — equivalent to `docker exec`.
- `image_build` accepts a `context` path — ensure it points to a project directory, not `/` or `/etc`.
- Inline `auth` credentials on `image_action` transit the MCP protocol (stdio). Prefer `docker login`.
- Plain TCP Docker sockets grant root access without authentication. Use SSH or TLS when accessing remote hosts.

## Development

```bash
# Install
npm install

# Dev server with hot reload
npm run dev

# Build
npm run build

# Test
npm test                 # Unit tests (no Docker needed)
npm run test:integration # Integration tests (requires Docker)
npm run lint             # Lint
npm run typecheck        # TypeScript check

# Format
npm run format
```

## Architecture

```
src/
  index.ts         — Entrypoint, DI wiring, stdio transport
  config.ts        — Docker client factory (reads DOCKER_HOST env vars)
  error.ts         — Centralized error handler with status-code mapper
  utils/
    compose.ts     — Compose arg builder + JSON output parser (pure)
    summarize.ts   — Token optimization utilities (field projection, ID truncation, ANSI stripping, output capping)
  tools/
    types.ts       — Shared types + tool registration helpers
    health.ts      — docker_ping (validates pipeline)
    containers.ts  — 5 container tools
    images.ts      — 3 image tools
    volumes.ts     — 2 volume tools
    networks.ts    — 2 network tools
    compose.ts     — 2 compose tools
    system.ts      — 2 system tools
```

## License

MIT