Docker MCP Guardian
Connects to the local Docker daemon to provide guarded container inspection and optional restart capabilities, with read-only defaults, credential redaction, canonical ID resolution, and bounded API timeouts.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Docker MCP Guardian
A security-hardened Model Context Protocol (MCP) server written in Python with FastMCP that connects local LLM agents (Claude Desktop, Claude Code) to the Docker daemon with strict zero-trust boundaries.
Core Capabilities & Safeguards
Read-Only by Default: Mutation tools (
safe_restart_container) reject calls before touching the Docker socket unlessGUARDIAN_ALLOW_WRITE=trueis explicitly set.Canonical ID Resolution: Resolves container IDs to Docker's internal canonical name before evaluating regex denylists, preventing evasion via hex IDs.
Credential & Secret Redaction:
inspect_containerstrips all environment variable values, returning only variable keys to prevent LLM prompt leakage.Isolated Stdio JSON-RPC: Strict logging separation ensures zero unstructured stdout writes, preventing JSON-RPC stream corruption in MCP clients.
Bounded Daemon Timeouts: Every Docker API call is capped by
GUARDIAN_DOCKER_TIMEOUT(default 5s), so a wedged or missing daemon returns a structureddaemon_unavailableerror instead of hanging the session.
Related MCP server: Docker-MCPilotS
Quickstart
Prerequisites
Python 3.10+
Docker Engine / Docker Desktop
mcp>=1.0.0,<2(pinned to FastMCP API)
Local Installation
git clone https://github.com/SivaSaiKrishnaSuryadevara/docker-mcp-guardian.git
cd docker-mcp-guardian
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pytest tests/ -vConnect to Claude Code
claude mcp add docker-guardian -- "$PWD/.venv/bin/python" "$PWD/server.py"For Claude Desktop, add the same interpreter and script paths (absolute) under mcpServers in claude_desktop_config.json.
Configuration
Variable | Default | Purpose |
|
| Must be |
|
| Containers that can never be restarted (always wins) |
| (unset) | If set, only matching containers can be restarted |
| error/exception/fatal/... | Pattern the log scanner flags |
|
| Total seconds one log scan may spend matching; slower scans return |
|
| Seconds per Docker API call |
|
| Log level (logs go to stderr only) |
| (unset) | Docker endpoint to use; always wins when set |
|
| Allow falling back to the rootful |
Docker endpoint resolution
Guardian picks its Docker endpoint in this order, and logs the choice to stderr:
DOCKER_HOST, if set.A rootless Docker socket:
$XDG_RUNTIME_DIR/docker.sock, then/run/user/<uid>/docker.sock. The second path covers MCP clients that start servers withoutXDG_RUNTIME_DIR.The rootful
/var/run/docker.sock, only whenGUARDIAN_ALLOW_ROOTFUL=true. Guardian logs a warning, because rootful API access is root-equivalent.
If none applies, tools return a docker_socket_unresolved error instead of connecting. The system socket is never used while a rootless socket exists.
Upgrading: earlier versions fell back to
/var/run/docker.socksilently. If you rely on the rootful daemon, setDOCKER_HOST=unix:///var/run/docker.sock(orGUARDIAN_ALLOW_ROOTFUL=true) in your MCP server definition. Docker Desktop and Colima users should setDOCKER_HOSTto their socket, for exampleunix://$HOME/.docker/run/docker.sockorunix://$HOME/.colima/default/docker.sock.
Rootless Docker
MCP clients (Claude Desktop, Claude Code, Cursor, Cline) start Guardian as a child process, often with a reduced environment that has no XDG_RUNTIME_DIR or DOCKER_HOST. Guardian still checks /run/user/<uid>/docker.sock, but if your rootless runtime directory is elsewhere, or you want the endpoint pinned, set DOCKER_HOST in the server definition:
{
"mcpServers": {
"docker-guardian": {
"command": "/path/to/docker-mcp-guardian/.venv/bin/python",
"args": ["/path/to/docker-mcp-guardian/server.py"],
"env": {
"DOCKER_HOST": "unix:///run/user/1000/docker.sock"
}
}
}
}Write the path literally: most clients do not expand $XDG_RUNTIME_DIR or $HOME in env. To find the value for your user, run either of these in a shell where rootless Docker works:
echo "unix://$XDG_RUNTIME_DIR/docker.sock"
docker context inspect rootless --format '{{.Endpoints.docker.Host}}'With Claude Code, the shell expands the variable when the server is added:
claude mcp add docker-guardian -e DOCKER_HOST="unix://$XDG_RUNTIME_DIR/docker.sock" -- "$PWD/.venv/bin/python" "$PWD/server.py"To confirm the endpoint is the rootless daemon, check that this lists name=rootless:
DOCKER_HOST=unix:///run/user/1000/docker.sock docker info --format '{{.SecurityOptions}}'On the first tool call, Guardian logs the endpoint it chose to stderr, for example Using Docker endpoint unix:///run/user/1000/docker.sock (DOCKER_HOST is set).
Write-up
The security model, tool surface, and policy engine are documented in docs/SECURITY_ARCHITECTURE.md.
Deep Dive & Publications
Don't Hand Claude Your Docker Socket — Build It a Guarded One (HackerNoon, October 21, 2026): why handing an AI agent the raw Docker socket is root-equivalent, and how this server's read-only default, canonical-name restart deny-list, secret redaction and bounded Docker API timeouts contain it.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Secure Linux sandboxes for AI agents, as MCP tools.
Zero-secret MCP gateway for AI agents: risk-scored, audited calls with human-in-the-loop approval.
MCP gateway with runtime security policy, tool-call-level control, and audit of agent actions.
Security & DLP proxy for MCP: tool-poisoning scans, PII redaction on tool args/results. Beta.
Related MCP Servers
- AlicenseNot gradedqualityNot gradedmaintenanceEnables AI assistants to interact with Docker containers through safe, permission-controlled access to inspect, manage, and diagnose containers, images, and compose services with built-in timeouts and AI-powered analysis.-
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to manage Docker containers through a secure MCP interface, supporting container lifecycle operations, log inspection, resource monitoring, and system diagnostics with role-based access control.3MIT
- AlicenseAqualityDmaintenanceEnables agentic Docker container operations including file read/write, command execution, and interactive TTY sessions via the local Docker binary.1914 npmMIT
- AlicenseNot gradedqualityBmaintenanceEnables read-only inspection and narrowly scoped maintenance of a local Docker Desktop environment, covering containers, images, logs, stats, Compose status, and Scout vulnerability/SBOM data, plus limited actions such as image pulls, container restarts, dangling-image pruning, and allowlisted Compose redeploys, all without exposing the raw Docker socket to the client.1MIT