docker-copilot-mcp

A local MCP server that lets Claude inspect and safely manage Docker containers on your machine — built as a hands-on project to learn the Model Context Protocol (tools, transports, state, and safety-gated destructive actions).

What it does

• Read-only inspection: list containers, get detailed status, fetch logs, check system health (CPU/memory/disk)
• Safe destructive actions: restart a container, but only after a two-step confirmation flow — the agent must first request a plan + token, then explicitly confirm before anything actually happens
• Scoped: only containers on an explicit whitelist can ever be restarted, regardless of what the agent is asked to do
• Audited: every tool call (especially restarts) is logged to a local SQLite database with timestamp, arguments, result, and success/failure

Why this project

Most MCP tutorials stop at "here's a tool that returns data." The interesting and hard part of building real agent tooling is deciding what an agent should be allowed to do without asking, and what it must never do without a human explicitly confirming. This project exists to practice that boundary, not just the MCP plumbing.

Architecture

Claude Desktop (MCP client) → stdio transport → FastMCP server (server.py) → Tools (list_containers, get_container_status, get_container_logs, get_system_health, restart_container) → Safety Gate (scope check → confirmation token → validate → execute) → Docker Client + Audit Log (SQLite)

The safety model

Every destructive tool (currently just restart_container) goes through a gate before touching Docker:

1. Scope check — is this target even allowed? The server maintains an explicit whitelist (safety/scope.py); anything outside it is refused immediately, no matter how the request is phrased.
2. Dry run by default — calling restart_container without a confirmation_token never restarts anything. It returns a plan description and a token bound to that exact action (tool + target + parameters).
3. Explicit confirmation — only a second call, with the matching token, actually executes. Tokens are single-use and expire after 2 minutes, so a stale or reused confirmation can't silently trigger an old, possibly outdated action.
4. Audit trail — both the dry-run request and the real execution are logged to SQLite, so there's always a record of what was proposed and what actually happened.

Setup

python -m venv venv
venv\Scripts\Activate.ps1
pip install -r requirements.txt

Requires Docker Desktop running locally.

Running

Manually (for testing):

python src/server.py

Via Claude Desktop: add to your config:

{
  "mcpServers": {
    "homelab-ops": {
      "command": "/absolute/path/to/venv/Scripts/python.exe",
      "args": ["/absolute/path/to/src/server.py"]
    }
  }
}

Tools

Tool	Type	Description
list_containers	read-only	List all containers, running or stopped
get_container_status	read-only	Detailed status for one container
get_container_logs	read-only	Recent logs from a container
get_system_health	read-only	Host CPU / memory / disk usage
restart_container	destructive, gated	Restart a container (requires confirmation)

Tests

pytest tests/test_safety_gate.py -v

What I learned building this

• The difference between MCP tools (actions) and the transport/routing layer
• Why destructive tool calls need a confirmation flow, not just try/except
• How to scope an agent's permissions explicitly, not just via prompt instructions
• Debugging a live MCP integration end-to-end, including finding that Claude Desktop reads config from a sandboxed AppData path, not the documented default

Possible extensions

• HTTP transport + OAuth for remote/shared access
• systemd service management alongside Docker
• Config-driven scope whitelist instead of hardcoded list
• /diagnose <container> prompt template for guided investigation