Skip to content
Back to search

docker-mcp-guardian

Security-hardened MCP server for Docker with read-only defaults, restart deny-lists, and secret redaction

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/SivaSaiKrishnaSuryadevara/docker-mcp-guardian with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/SivaSaiKrishnaSuryadevara/docker-mcp-guardian'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/sivasaikrishnasuryadevara--docker-mcp-guardian/badge.svg)](/listings/sivasaikrishnasuryadevara--docker-mcp-guardian)

HTML

<a href="/listings/sivasaikrishnasuryadevara--docker-mcp-guardian"><img src="/api/listings/sivasaikrishnasuryadevara--docker-mcp-guardian/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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/ -v

Connect 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`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 111 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Docker MCP Guardian
  2. 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.
  3. [![CI](https://github.com/SivaSaiKrishnaSuryadevara/docker-mcp-guardian/actions/workflows/ci.yml/badge.svg)](https://github.com/SivaSaiKrishnaSuryadevara/docker-mcp-guardian/actions)
  4. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  5. ## Core Capabilities & Safeguards
  6. - **Read-Only by Default:** Mutation tools (`safe_restart_container`) reject calls before touching the Docker socket unless `GUARDIAN_ALLOW_WRITE=true` is explicitly set.
  7. - **Canonical ID Resolution:** Resolves container IDs to Docker's internal canonical name before evaluating regex denylists, preventing evasion via hex IDs.
  8. - **Credential & Secret Redaction:** `inspect_container` strips all environment variable values, returning only variable keys to prevent LLM prompt leakage.
  9. - **Isolated Stdio JSON-RPC:** Strict logging separation ensures zero unstructured stdout writes, preventing JSON-RPC stream corruption in MCP clients.
  10. - **Bounded Daemon Timeouts:** Every Docker API call is capped by `GUARDIAN_DOCKER_TIMEOUT` (default 5s), so a wedged or missing daemon returns a structured `daemon_unavailable` error instead of hanging the session.
  11. ## Quickstart
  12. ### Prerequisites
  13. - Python 3.10+
  14. - Docker Engine / Docker Desktop
  15. - `mcp>=1.0.0,<2` (pinned to FastMCP API)
  16. ### Local Installation
  17. ```bash
  18. git clone https://github.com/SivaSaiKrishnaSuryadevara/docker-mcp-guardian.git
  19. cd docker-mcp-guardian
  20. python3 -m venv .venv
  21. source .venv/bin/activate
  22. pip install -r requirements.txt
  23. pytest tests/ -v
  24. ```
  25. ### Connect to Claude Code
  26. ```bash
  27. claude mcp add docker-guardian -- "$PWD/.venv/bin/python" "$PWD/server.py"
  28. ```
  29. For Claude Desktop, add the same interpreter and script paths (absolute) under `mcpServers` in `claude_desktop_config.json`.
  30. ## Configuration
  31. | Variable | Default | Purpose |
  32. |---|---|---|
  33. | `GUARDIAN_ALLOW_WRITE` | `false` | Must be `true` for `safe_restart_container` to do anything |
  34. | `GUARDIAN_RESTART_DENY_REGEX` | `^(prod\|db\|kube\|vault)-.*` | Containers that can never be restarted (always wins) |
  35. | `GUARDIAN_RESTART_ALLOW_REGEX` | *(unset)* | If set, only matching containers can be restarted |
  36. | `GUARDIAN_ANOMALY_REGEX` | error/exception/fatal/... | Pattern the log scanner flags |
  37. | `GUARDIAN_REGEX_TIMEOUT` | `1` | Total seconds one log scan may spend matching; slower scans return `regex_timeout` |
  38. | `GUARDIAN_DOCKER_TIMEOUT` | `5` | Seconds per Docker API call |
  39. | `GUARDIAN_LOG_LEVEL` | `INFO` | Log level (logs go to stderr only) |
  40. | `DOCKER_HOST` | *(unset)* | Docker endpoint to use; always wins when set |
  41. | `GUARDIAN_ALLOW_ROOTFUL` | `false` | Allow falling back to the rootful `/var/run/docker.sock` |
  42. ### Docker endpoint resolution
  43. Guardian picks its Docker endpoint in this order, and logs the choice to stderr:
  44. 1. `DOCKER_HOST`, if set.
  45. 2. A rootless Docker socket: `$XDG_RUNTIME_DIR/docker.sock`, then `/run/user/<uid>/docker.sock`. The second path covers MCP clients that start servers without `XDG_RUNTIME_DIR`.
  46. 3. The rootful `/var/run/docker.sock`, only when `GUARDIAN_ALLOW_ROOTFUL=true`. Guardian logs a warning, because rootful API access is root-equivalent.
  47. If none applies, tools return a `docker_socket_unresolved` error instead of connecting. The system socket is never used while a rootless socket exists.
  48. > **Upgrading:** earlier versions fell back to `/var/run/docker.sock` silently. If you rely on the rootful daemon, set `DOCKER_HOST=unix:///var/run/docker.sock` (or `GUARDIAN_ALLOW_ROOTFUL=true`) in your MCP server definition. Docker Desktop and Colima users should set `DOCKER_HOST` to their socket, for example `unix://$HOME/.docker/run/docker.sock` or `unix://$HOME/.colima/default/docker.sock`.
  49. ### Rootless Docker
  50. 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:
  51. ```json
  52. {
  53. "mcpServers": {
  54. "docker-guardian": {
  55. "command": "/path/to/docker-mcp-guardian/.venv/bin/python",
  56. "args": ["/path/to/docker-mcp-guardian/server.py"],
  57. "env": {
  58. "DOCKER_HOST": "unix:///run/user/1000/docker.sock"
  59. }
  60. }
  61. }
  62. }
  63. ```
  64. 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:
  65. ```bash
  66. echo "unix://$XDG_RUNTIME_DIR/docker.sock"
  67. docker context inspect rootless --format '{{.Endpoints.docker.Host}}'
  68. ```
  69. With Claude Code, the shell expands the variable when the server is added:
  70. ```bash
  71. claude mcp add docker-guardian -e DOCKER_HOST="unix://$XDG_RUNTIME_DIR/docker.sock" -- "$PWD/.venv/bin/python" "$PWD/server.py"
  72. ```
  73. To confirm the endpoint is the rootless daemon, check that this lists `name=rootless`:
  74. ```bash
  75. DOCKER_HOST=unix:///run/user/1000/docker.sock docker info --format '{{.SecurityOptions}}'
  76. ```
  77. 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).`
  78. ## Write-up
  79. The security model, tool surface, and policy engine are documented in [docs/SECURITY_ARCHITECTURE.md](docs/SECURITY_ARCHITECTURE.md).
  80. ## Deep Dive & Publications
  81. - **[Don't Hand Claude Your Docker Socket — Build It a Guarded One](https://hackernoon.com/dont-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.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.