jpanasuk/dockroot-mcp-source

🐳 dockroot-mcp — Virtual Docker Root for AI Agents

Give your AI agent read-only power over its own Docker stack — without host root.

dockroot-mcp is a standalone MCP server that exposes read-only Docker tools (ps, logs, inspect, stats, networks) as first-class agent tools. Drop the container into any compose stack, mount the socket, and your agent can SEE and DIAGNOSE every container on its network — then actually fix things, instead of guessing.

Why this exists

AI agents get asked "why is my Open WebUI broken?" constantly. Without docker access they flail: they invent commands, read the wrong configs, or hallucinate fixes. With dockroot-mcp the agent can:

1. List the containers on its network (docker_ps)
2. Read logs to find the real error (docker_logs)
3. Inspect env / mounts / health (docker_inspect)
4. Watch CPU/memory pressure (docker_stats)
5. See the network topology (docker_networks)

Then it answers from evidence, not imagination. The Fixer sees the box.

The security model (read this)

• Read-only by design — the MCP tool list contains ONLY read commands. No start/stop/rm/exec. The agent can diagnose, never destroy.
• Scoped visibility — mount the socket, and the tools see the whole Docker daemon the socket belongs to. Keep it on an internal network.
• Opt-in — no socket mount, no docker access. The server still runs (it just reports the docker error honestly).
• Env filtering — Hermes strips secrets from MCP subprocess env and redacts credentials in tool errors.

This is virtual root: the power of sight without the power of control.

Quick start

1. Add to your compose stack

services:
  dockroot:
    image: jpanasuk/dockroot-mcp:latest
    container_name: dockroot
    restart: unless-stopped
    networks: [your-ai-network]            # the network it can see
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock   # read-only docker access

2. Connect from Hermes (native MCP client)

# ~/.hermes/config.yaml
mcp_servers:
  dockroot:
    command: python3
    args: ["/opt/dockroot/tavern_mcp.py"]

Then ask your agent: "what containers are running?" or "why is code-server crash-looping?" — it calls mcp_dockroot_docker_ps / mcp_dockroot_docker_logs and answers from the actual stack.

3. Or expose through MCPO (Open WebUI ecosystem)

Add to your mcpo config.json:

{
  "mcpServers": {
    "dockroot": {
      "command": "python3",
      "args": ["/opt/dockroot/tavern_mcp.py"]
    }
  }
}

Every tool becomes an HTTP endpoint (/dockroot/docker_ps, ...) that any OpenAI-compatible tool caller can hit.

Available tools

Tool	What it does	When to use
docker_ps	List containers (names, images, status, ports)	"what's running?"
docker_logs	Tail a container's logs	"why is X failing?"
docker_inspect	Full config: env, mounts, network, health	"what env does X have?"
docker_stats	Live CPU/memory usage	"is the box overloaded?"
docker_networks	List Docker networks	"what networks exist?"
status	Discovered services with link:port	"what's connected?"
self_check	Verify every service's health (HTTP+TCP)	"is everything working?"
wire	Wiring audit with exact fixes	"connect X to Y"
rediscover	Re-scan the network	"find new services"
models	List available models	"what models can I use?"
chat	One-shot chat with the primary engine	"ask the model something"

Use cases

• Self-healing stacks — an agent that reads its own logs, finds the crash, and applies the fix from a recipe
• Onboarding — "show me everything that's running" with actual output, not a hallucinated list
• Support triage — a support agent inspects logs + configs before escalating
• Multi-model troubleshooting — an agent compares what Open WebUI sees vs what Ollama serves, using evidence from both
• Dev sandboxes — ephemeral stacks where the agent is expected to self-diagnose

Why "virtual docker root"

Docker socket access normally equals host root — a container with the socket can run anything. dockroot-mcp deliberately stays on the safe side of that line: all tools are read-only, and the server is the only thing that talks to the socket. The agent gets X-ray vision, not a weapon. If you ever need write access, fork it and add your own tools — the read-only boundary is the default, not the ceiling.

Security notes

• The image runs as root (the socket needs it) — keep it internal
• Never expose dockroot-mcp's port publicly
• The mcp Python package is installed so Hermes can act as the client
• Tools return truncated output (4KB stdout / 2KB stderr) to protect context windows

Development

• tavern_mcp.py — the MCP server (pure stdlib protocol, no framework)
• discover.py / recipes.py — the discovery + fix-recipe engine
• Dockerfile — python:3.12-slim + docker CLI + mcp SDK

Devlog

2026-08-10 — v1.0.6 (initial release)

• Standalone MCP server exposing the tavern connectivity toolkit + 5 read-only docker tools
• Proper MCP stdio handshake (fixed the stub that sent unsolicited initialize messages → "Connection closed")
• Fallback discovery paths so the server runs both inside basecamp (/opt/basecamp) and standalone (/opt/dockroot)
• os import fix (the one that crashed tavern_or_discover)
• Verified: hermes native MCP client connects (6+5 tools), MCPO connects and calls tools, docker_ps lists the live stack from inside a container
• Built on the basecamp 1.0.6 adaptive discovery engine (subnet sweep, cross-host hosts, 44 fix recipes)

---

Built with the Basecamp project — the portable AI agent container with network auto-discovery. Hermes Agent by Nous Research under the hood.