sivasaikrishnasuryadevara/docker-mcp-guardian

开发工具

本页由 AI 翻译，技术细节请以原文为准。查看原文

109 stars 109 forks 质量 85 趋势 35MIT

Repository Install

为Docker提供安全防护的MCP服务器，支持只读默认、重启拒绝列表和秘密遮蔽功能

概览

一台安全防护的模型上下文协议（MCP）服务器，使用 Python 编写，使用 FastMCP 编写，将本地 LLM 代理（Claude Desktop、Claude Code）连接到 Docker 守护进程，并严格限制零信任边界。 - 变异工具（safe_restart_container）在触及 Docker 套接字前拒绝调用，除非明确设置 GUARDIAN_ALLOW_WRITE=true。- 在评估正规表达式拒绝列表前，将容器 ID 解析为 Docker 内部规范名称，防止通过十六进制 ID 规避。- inspect_container 剥离所有环境变量值，只返回变量键，防止 LLM 提示符泄露。- 严格的日志分离确保零非结构化 stdout 写入，防止 MCP 客户端的 JSON-RPC 流损坏。- 每个 Docker API 调用都以 GUARDIAN_DOCKER_TIMEOUT（默认 5 个）封闭，因此楔形或缺失的守护进程会返回结构化 daemon_unavailable 错误，而不会挂断会话。 - Python 3.10+ - Docker Engine / Docker Desktop - mcp>=1.0。

概述（AI 翻译）

一台安全防护的模型上下文协议（MCP）服务器，使用 Python 编写，使用 FastMCP 编写，将本地 LLM 代理（Claude Desktop、Claude Code）连接到 Docker 守护进程，并严格限制零信任边界。

核心能力与保障措施

默认只读： 变异工具（safe_restart_container）在触及Docker套接字前拒绝调用，除非明确设置GUARDIAN_ALLOW_WRITE=true。
规范ID解析： 在评估正规表达式拒绝者之前，将容器ID解析为Docker内部规范名称，防止通过十六进制ID规避。
凭证与秘密编辑： inspect_container 剥离所有环境变量值，只返回变量键，以防止LLM提示符泄露。
隔离标准 JSON-RPC： 严格的日志分离确保零非结构化标准输出写入，防止 MCP 客户端的 JSON-RPC 流损坏。
有界守护进程超时： 每次 Docker API 调用都被 GUARDIAN_DOCKER_TIMEOUT（默认 5s）限制，因此楔形或缺失的守护进程会返回结构化的 daemon_unavailable 错误，而不是挂断会话。

快速开始

先决条件

Python 3.10+
Docker Engine / Docker Desktop
'MCP>=1.0。

本页由 AI 翻译，技术细节请以原文为准。

README

以下为原文 README 节选，完整内容请查看原文。

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 unless GUARDIAN_ALLOW_WRITE=true is 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_container strips 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 structured daemon_unavailable error instead of hanging the session.

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

Configuration

Variable	Default	Purpose
`GUARDIAN_ALLOW_WRITE`	`false`	Must be `true` for `safe_restart_container` to do anything
`GUARDIAN_RESTART_DENY_REGEX`	`^(prod\|db\|kube\|vault)-.*`	Containers that can never be restarted (always wins)
`GUARDIAN_RESTART_ALLOW_REGEX`	(unset)	If set, only matching containers can be restarted
`GUARDIAN_ANOMALY_REGEX`	error/exception/fatal/…	Pattern the log scanner flags
`GUARDIAN_REGEX_TIMEOUT`	`1`	Total seconds one log scan may spend matching; slower scans return `regex_timeout`
`GUARDIAN_DOCKER_TIMEOUT`	`5`	Seconds per Docker API call
`GUARDIAN_LOG_LEVEL`	`INFO`	Log level (logs go to stderr only)
`DOCKER_HOST`	(unset)	Docker endpoint to use; always wins when set
`GUARDIAN_ALLOW_ROOTFUL`	`false`	Allow falling back to the rootful `/var/run/docker.sock`

Docker endpoint resolution

在 GitHub 查看完整 README

安装

This server does not publish a one-line install command.

Open the repository installation guide 新手？先看 mcpskill.org 教程 →

配置

{
  "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"
      }
    }
  }
}