docker-mcp-server

<div align="center"> <a href="https://soyrage.es/"> <img src="./assets/soyrage-banner.svg" alt="SoyRage Agency — 全栈开发 × 基础设施工程师 · soyrage.es" width="100%"> </a> <br/> # 🐳 Docker MCP 服务器 **与您的 Docker 主机聊天。** 一个 [模型上下文协议](https://modelcontextprotocol.io) 服务器，可以将任何支持 MCP 的 AI（如 Claude Desktop、Cursor、Continue、Zed）变成一个自然语言的 DevOps 副驾驶员，用于 **Docker 和 Docker Compose**。 *“重启 `api` 容器。” · “为什么 `web` 崩溃了 — 显示我最后 100 行日志。” · “在 `./prod` 中部署堆栈并确认它运行正常。”* <br/> [](https://github.com/soyrageagency/docker-mcp-server/actions/workflows/ci.yml) [](https://nodejs.org) [](https://www.typescriptlang.org/) [](https://modelcontextprotocol.io) [](https://docs.docker.com/engine/api/) [](./LICENSE) [](https://www.paypal.com/paypalme/soyrageagency) ### 由 **[SoyRage Agency](https://soyrage.es/)** 设计、构建和维护 · **https://soyrage.es/** **⚡ 新来者？一键安装 → [快速安装](#-快速安装一键)**。 · **☕ 支持该项目](https://www.paypal.com/paypalme/soyrageagency)** </div> --- ## 📑 目录 - [快速安装（一键）](#-快速安装一键) - [这是什么？](#-这是什么) - [为什么它存在](#-为什么它存在) - [功能概述](#-功能概述) - [交互式面板](#-交互式面板) - [终端 UI（TUI）](#-终端-ui-tui) - [监控：Prometheus、Zabbix 等](#-监控prometheus-zabbix-等) - [模块化插件架构](#-模块化插件架构) - [工作原理](#-工作原理) - [需求](#-需求) - [安装](#-安装) - [连接到您的 AI 客户端](#-连接到您的-ai-客户端) - [Claude Desktop](#claude-desktop) - [Cursor / Continue / Zed](#cursor--continue--zed) - [配置参考](#-配置参考) - [连接到远程 / TLS 守护进程](#-连接到远程--tls-守护进程) - [安全模型](#-安全模型) - [完整的工具参考](#-完整的工具参考) - [示例对话](#-示例对话) - [项目结构](#-项目结构) - [设计原则](#-设计原则) - [开发](#-开发) - [故障排除和常见问题](#-故障排除和常见问题) - [路线图](#-路线图) - [贡献](#-贡献) - [关于 SoyRage Agency](#-关于-soyrage-agency) - [支持该项目](#-支持该项目) - [致谢和许可证](#-致谢和许可证) --- ## ⚡ 快速安装（一键） 新来者？安装程序克隆该项目，构建它，并为您**配置 Claude Desktop** — 无需手动 JSON 编辑。您只需要 [Git](https://git-scm.com/) 和 [Node.js ≥ 18](https://nodejs.org/)。 **Windows（PowerShell）：** ```powershell irm https://raw.githubusercontent.com/soyrageagency/docker-mcp-server/main/install.ps1 | iex ``` **macOS / Linux：** ```bash curl -fsSL https://raw.githubusercontent.com/soyrageagency/docker-mcp-server/main/install.sh | bash ``` 已经克隆了仓库？只需运行： ```bash npm run setup # 构建并配置 Claude Desktop ``` 然后 **重启 Claude Desktop** 并询问：*“哪些 Docker 容器正在运行？”* 🎉 安装程序 **备份** 您现有的配置并 **合并** 条目，因此您已有的其他 MCP 服务器得以保留。如果您更喜欢查看代码段而不输入任何内容，可以运行 `node scripts/install.mjs --print`。 > 💙 如果这为您节省了时间，请 [**在 PayPal 上支持该项目**](https://www.paypal.com/paypalme/soyrageagency) 并给一个 ⭐ — 这真的有助于 SoyRage Agency 继续在开放的环境中进行开发。 --- ## 🧭 这是什么？ **模型上下文协议（MCP）** 是一个开放标准，允许 AI 助手通过定义良好的 JSON-RPC 接口与外部工具通信。**Docker MCP 服务器** 是一个 MCP *服务器*，它通过 **stdio** 使用该协议，并将您的 Docker 主机公开为一组安全、丰富描述的工具。 将任何支持 MCP 的助手指向它，您就可以用 **自然语言** 操作容器和 Compose 堆栈 — 模型读取每个工具的模式，决定调用哪个，并将结果报告给您。不需要记住标志或复制粘贴容器 ID。 > **一句话：** 它是“*我希望我可以直接告诉我的服务器该怎么做*”和您的实际 Docker 守护进程之间的桥梁。 --- ## 💡 为什么它存在 日常容器工作是一系列小型、重复的命令： ```bash docker ps -a docker logs --tail 100 -f my-api docker compose -f ./prod/compose.yaml up -d --build docker stats my-api ``` 每个命令都很容易 *一旦你记住确切的语法*。摩擦来自记忆和上下文切换。该服务器通过让 AI 进行翻译来消除这种摩擦，同时通过以下方式 **保持您可控**： - **只读模式** 用于安全的演示和生产洞察。 - **容器允许列表**，因此助手只能访问您允许的内容。 - **选择性执行**，因此任意的容器内命令不会意外地可用。 - **确认友好设计** — 破坏性工具被清楚地描述，因此模型在执行前会询问。 由 **[SoyRage Agency](https://soyrage.es/)** 为自托管和家庭实验室社区构建 — 同样适用于 CI 运行器或生产 VM 后面的只读模式。 --- ## 🚀 功能概述 | 领域 | 功能 | | --- | --- | | 🔎 **洞察** | 列出容器 · 检查完整配置 · 实时 CPU/内存/网络统计 · 尾部日志，带有时间窗口 · 列出镜像 / 网络 / 卷 · 主机摘要 · 磁盘使用情况。 | | ⚙️ **生命周期** | 启动 · 停止 · 重启 · 删除容器 — 带有温和的停止超时。 | | 📦 **Compose** | 验证配置 · 列出服务和健康状态 · **部署** (`up -d`，可选 `--build`) · 拆除 · 重启 · 拉取 — 通过官方 `docker compose` CLI。 | | 🛡️ **安全** | 全局 **只读** 模式 · **容器允许列表** · **选择性执行** · 软属性保护。 | | 🔌 **传输** | 本地 Unix 套接字 · Windows 命名管道 · 安全的远程 **TCP + TLS**。 | | 🎨 **身份** | ASCII 欢迎横幅 · `about` 工具 · MCP `instructions` 在连接时向 AI 致敬 **SoyRage Agency**。 | | 🖥️ **交互式面板** | 标签式网页仪表板：实时监控，**终端，带有智能命令建议**，**文件资源管理器**，**快照和定时备份**，**网络/卷**，**自动重启监视器**，**警报和日志监视**，检查，搜索和生命周期操作 — 带有演示模式。 | | ⌨️ **终端 UI** | 创意，lazydocker 风格的 TUI，带有 SoyRage 欢迎，实时仪表和一键操作 — 零 curses 依赖。 | | 📈 **监控** | 内置 **Prometheus `/metrics`** 端点 — 从 Prometheus、Grafana、Zabbix、VictoriaMetrics 等中抓取。 | | 🧩 **模块化** | 每个功能都是一个可切换的 **插件**；通过配置启用您想要的确切功能。 | | 🧱 **工程** | 100% TypeScript，严格模式 · 每个关注点一个模块 · 微小的依赖关系 · 仅 stderr 日志。 | --- ## 🖥️ 交互式面板 除了对话界面外，该项目还附带了一个 **极简主义网页仪表板** (`docker-mcp-panel`)，适用于您想要快速、视觉、点击即操作的 Docker 主机视图时。它重用了相同的配置、Docker 客户端和安全防护措施，因此 **只读模式** 和 **允许列表** 也适用于此处。 ```bash npm run build npm run panel # → http://127.0.0.1:4600 npm run panel:demo # 相同，但带有现实的模拟数据（无需守护进程） ``` <div align="center"> ### 仪表板 — 实时主机统计数据、容器和镜像 <img src="./assets/screenshots/01-dashboard.png" alt="Docker 面板仪表板 by SoyRage Agency" width="90%"> ### 一键尾部日志 <img src="./assets/screenshots/02-logs.png" alt="Docker 面板日志抽屉 by SoyRage Agency" width="90%"> ### 终端 — 运行带有智能建议的 docker 命令（Tab / ↑↓ / Enter） <img src="./assets/screenshots/08-terminal.png" alt="Docker 面板终端，带有 SoyRage Agency 的命令建议" width="90%"> ### 快照和定时备份 — 带有电子邮件/云交付 <img src="./assets/screenshots/09-backups.png" alt="Docker 面板快照和定时备份 by SoyRage Agency" width="90%"> ### 文件资源管理器 + 编辑器 — 视图和编辑容器内的文件 <img src="./assets/screenshots/11-editor.png" alt="Docker 面板文件编辑器 by SoyRage Agency" width="90%"> ### 浏览容器的文件系统 <img src="./assets/screenshots/06-files.png" alt="Docker 面板文件资源管理器 by SoyRage Agency" width="90%"> ### 系统 — 网络和卷 <img src="./assets/screenshots/10-system.png" alt="Docker 面板网络和卷 by SoyRage Agency" width="90%"> ### 警报和日志监视 — 带有实时自动重启监视器 <img src="./assets/screenshots/07-alerts.png" alt="Docker 面板警报和自动重启 by SoyRage Agency" width="90%"> ### 只读模式 — 操作安全禁用 <img src="./assets/screenshots/03-readonly.png" alt="Docker 面板只读模式 by SoyRage Agency" width="90%"> _{截图在 <b>演示模式</b> 下渲染 · 水印 © SoyRage Agency · soyrage.es} </div> **面板亮点** - **标签式布局** — *概览*、*终端*、*文件*、*备份*、*系统* 和 *警报*，带有标题中的实时警报徽章。 - **实时监控 + 趋势** — CPU 负载和内存使用仪表带有表盘，每个容器的 CPU % 和内存条，以及随时间变化的历史火花线图表（每 5 秒采样）。 - **⌨️ AI 驱动的终端** — 输入 `docker …` 以获得宽容的、上下文相关的补全（**Tab**/**↑↓**/**Enter**），**或** 输入纯英文请求并选择 **询问 AI** — 副驾驶建议一个命令，您审查后运行。命令被解析为 argv 数组并在没有 shell 的情况下生成；拒绝列表阻止危险动词，写动词尊重只读模式。AI 使用任何 OpenAI 兼容的端点（OpenAI、**Ollama**、LM Studio …）；如果没有，它会回落到基于规则的建议。 - **📁 文件资源管理器 + 编辑器** — 浏览任何容器的文件系统（面包屑、向上导航），**打开和编辑** 文本/.sh/配置文件，并 **保存** 到容器中。**AI 编辑** 按钮从纯英文指令重写文件。安全的 shell 免费 `exec`；编辑在只读模式下被阻止。 - **📸 快照和定时备份** — 将容器快照为镜像（`commit`）或文件系统 `export`（`.tar`）到选择的目录；安排每日备份（时间、容器、类型）；**Webhook** 将每个备份转发到 **电子邮件、Google Drive 或 S3**，通过 Zapier / Make / n8n。 - **🧩 系统选项卡** — 一目了然的网络和卷；每个容器的 **检查** 详细信息（环境变量、挂载、端口、重启策略）在抽屉中。 - **♻️ 自动重启监视器** — 切换 *自动* 切换后，监视器在容器退出时重启（尊重只读模式）。 - **🚨 警报和日志监视** — 容器关闭/不健康、CPU/内存高、监视器事件，以及 **错误/警告日志行** 从最近的日志中扫描。 - **容器网格** — 颜色编码的状态点、端口作为芯片、**过滤/搜索**、**自动刷新** 切换和每行操作（详细信息 · 文件 · 快照 · 启动/停止/重启）。 - **Prometheus `/metrics`** — 页脚链接公开抓取端点（参见 [监控](#-监控prometheus-zabbix-等））。 - **演示模式** — `DOCKER_MCP_PANEL_DEMO=true` 提供模拟但现实的数据（带有轻微的实时抖动），适用于预览和客户演示，无需守护进程。 - **零 UI 依赖** — 手写的 HTML/CSS/JS 由 Node-core HTTP 服务器提供服务。 **面板 REST API**（全部本地）：`/api/snapshot` · `/api/history` · `/api/containers` · `/api/images` · `/api/logs` · `/api/action` · `/api/run` · `/api/ai` · `/api/files` · `/api/file`（GET 读取 / POST 保存） · `/api/inspect` · `/api/networks` · `/api/volumes` · `/api/backups` · `/api/schedule` · `/api/alerts` · `/api/autorestart` · `/metrics`。 **AI 副驾驶（可选）**：设置 `DOCKER_MCP_AI_ENDPOINT`（+ `DOCKER_MCP_AI_KEY`，`DOCKER_MCP_AI_MODEL`）以启用 AI 终端和 AI 文件编辑。适用于 **OpenAI**、**Ollama** (`http://localhost:11434/v1`，免费 & 本地）、**LM Studio**，或任何 OpenAI 兼容的 API。演示模式模拟它，以便您可以离线尝试 UX。 > 🖼️ 使用 `npm run shots` 自制截图（需要 `npx playwright install chromium`）。 ### 🔒 面板安全 & 网络（VPN、IP、端口） 面板和终端可以控制您的主机，因此像 SSH 一样处理访问。 - **默认本地绑定** — 面板监听 `127.0.0.1:4600`。通过 **隧道一个 VPN** — [WireGuard](https://www.wireguard.com/) 或 [Tailscale](https://tailscale.com/) — 并浏览到主机的 VPN IP 地址。**不要**将面板的端口转发到公共互联网。 - **如果您必须绑定到 LAN**，请设置 `DOCKER_MCP_PANEL_HOST=0.0.0.0`。启动时，服务器会打印 **它可以访问的所有 IP 地址** 和一个警告，例如： ``` 面板已在 http://0.0.0.0:4600 可访问于 http://127.0.0.1:4600 可访问于 http://10.8.0.3:4600 ← 您的 WireGuard IP 可访问于 http://192.168.1.42:4600 ← 您的 LAN IP 面板绑定到所有接口... 请将其放在 VPN 或经过身份验证的反向代理后面。 ``` - **更改端口** 使用 `DOCKER_MCP_PANEL_PORT`（例如 `8443`）以避免冲突或位于反向代理后面。 - **端口转发 / 反向代理** — 如果您公开它，请在前面放置一个经过身份验证的代理（Caddy/nginx/Traefik 带有 Basic-Auth 或 SSO + TLS）。将其与 `DOCKER_MCP_READONLY=true` 结合使用以进行仅查看部署，并使用 `DOCKER_MCP_PANEL_TERMINAL=false` 禁用命令运行程序。 --- ## ⌨️ 终端 UI（TUI） 喜欢终端？启动 **`docker-mcp-tui`** — 一个创意、 [lazydocker](https://github.com/jesseduffield/lazydocker) 风格的仪表板，带有 SoyRage 欢迎信息，然后将其放入实时、键盘驱动的视图中。它是手工滚动的 ANSI（无 curses 库），因此它只会增加 **零依赖**。 ```bash npm run tui # → 交互式终端仪表板 npm run tui:demo # 相同，但带有现实的模拟数据（无需守护进程） ``` <div align="center"> ### 欢迎信息 — “感谢您使用我们的仓库 ⭐” <img src="./assets/screenshots/05-tui-welcome.png" alt="SoyRage Agency 终端欢迎信息" width="80%"> ### 实时仪表板 — 仪表、详细信息和一键操作 <img src="./assets/screenshots/04-tui.png" alt="Docker MCP 终端 UI by SoyRage Agency" width="88%"> </div> **按键：** `↑/↓` （或 `j/k`）导航 · `l` 切换日志 · `S` 启动 · `s` 停止 · `R` 重启 · `r` 刷新 · `q` 退出。 实时 CPU/内存仪表自动刷新；只读模式隐藏操作键。 --- ## 📈 监控：Prometheus、Zabbix 等 面板兼作 **指标导出器**。它在 **`/metrics`** 处提供标准 Prometheus 文本端点，因此您的 Docker 主机成为具有 **无额外代理** 的一流监控目标。 ```bash npm run panel # 默认情况下启用指标 curl http://127.0.0.1:4600/metrics ``` **公开的系列**（按相关性标记 `name`、`state`、`image`）： | 指标 | 类型 | 含义 | | --- | --- | --- | | `dockermcp_up` | gauge | 导出器运行时为 1。 | | `dockermcp_build_info` | gauge | 构建/作者元数据（产品、**作者 = SoyRage Agency**、版本、url）。 | | `dockermcp_host_cpus` | gauge | 主机上的逻辑 CPU。 | | `dockermcp_host_memory_bytes` | gauge | 主机总内存。 | | `dockermcp_containers_total` / `_running` | gauge | 容器计数。 | | `dockermcp_images_total` | gauge | 缓存的镜像。 | | `dockermcp_cpu_percent_total` | gauge | 容器 CPU 总量%。 | | `dockermcp_memory_used_bytes` | gauge | 容器内存总量。 | | `dockermcp_container_running{…}` | gauge | 如果给定容器正在运行，则为 1。 | | `dockermcp_container_cpu_percent{…}` | gauge | 每个容器的 CPU%。 | | `dockermcp_container_memory_bytes{…}` | gauge | 每个容器的内存。 | | `dockermcp_container_autorestart{…}` | gauge | 如果启用了自动重启，则为 1。 | | `dockermcp_autorestart_enabled` | gauge | 自动重启容器计数。 | | `dockermcp_alerts_active` | gauge | 活动状态警报数量。 | ### Prometheus ```yaml # prometheus.yml scrape_configs: - job_name: docker-mcp static_configs: - targets: ["your-host:4600"] ``` ### Zabbix 使用一个指向 `http://your-host:4600/metrics` 的 **HTTP 代理** 项，然后添加 依赖项为 **Prometheus 模式** 预处理步骤，例如 `dockermcp_containers_running` 或 `dockermcp_container_cpu_percent{name="api"}`。Grafana、Grafana Agent、 VictoriaMetrics 和 Netdata 可以抓取相同的端点。 > 如果您只需要 UI，请将导出器关闭并设置 `DOCKER_MCP_PANEL_METRICS=false`。 --- ## 🧩 模块化插件架构 服务器由独立的**插件**组成，每个插件拥有一个功能组。加载哪些插件完全由配置驱动，因此您可以根据需要公开确切的界面——从*仅限洞察*到完整的工具箱——**无需修改代码**。这也使得项目易于扩展，并且由于在锁定插件中内置了署名，因此很难在不注意到溯源的情况下进行整体分叉。 | 插件 | 类别 | 类型 | 工具 | | --- | --- | --- | --- | | `about` 🔒 | 身份 | 读取 | `about`, `list_plugins` | | `containers` | 洞察 | 读取 | `list_containers`, `inspect_container`, `container_stats` | | `logs` | 洞察 | 读取 | `container_logs` | | `images` | 洞察 | 读取 | `list_images` | | `system` | 系统 | 读取 | `system_info`, `disk_usage`, `list_networks`, `list_volumes` | | `compose` | compose | 读取/写入 | `compose_ps`, `compose_config`, `deploy_stack`, `compose_down`, `compose_restart`, `compose_pull` | | `lifecycle` | 生命周期 | 写入 | `start`/`stop`/`restart`/`remove_container`, `exec_in_container` | _{🔒 `about`插件是**锁定的**——它带有SoyRage Agency身份标识，无法禁用。} **通过环境变量或配置文件**切换插件： ```bash # 仅公开只读洞察（一个安全、精选的界面） DOCKER_MCP_PLUGINS=containers,logs,images,system # 加载除容器生命周期之外的所有内容 DOCKER_MCP_DISABLED_PLUGINS=lifecycle ``` 随时向助手**“列出插件”**以查看已启用的插件。 ### 配置文件 为了实现可复制的设置，请在项目根目录中添加一个 **`docker-mcp.config.json`**（或将 `DOCKER_MCP_CONFIG` 指向一个）： ```json { "readOnly": false, "allowExec": false, "containerAllowlist": ["web", "api"], "plugins": { "enabled": [], "disabled": ["lifecycle"] }, "panel": { "host": "127.0.0.1", "port": 4600, "demo": false } } ``` **配置优先级**（从低到高）：内置默认值 → `docker-mcp.config.json` → `.env` → 实际环境变量。 --- ## 🛠️ 工作原理 ``` ┌──────────────────────────────────────────────┐ 您 ◀──────▶ │ AI 助手（Claude / Cursor / Continue …） │ └───────────────────────┬──────────────────────┘ stdio · JSON‑RPC (MCP) ┌───────────────────────▼──────────────────────┐ │ Docker MCP 服务器 │ │ │ │ 1. 客户端发送 `initialize` → 服务器 │ │ 回复工具模式 + SoyRage `指令`（身份和欢迎）。 │ │ 2. 模型选择工具并发送 `tools/call`。│ │ 3. 服务器执行它并返回人类可读文本。 │ └───────────┬───────────────────────┬──────────┘ 引擎 API │ spawn │ docker compose ┌───────────▼───────────┐ ┌──────────▼──────────┐ │ Docker 引擎 │ │ Compose 插件 │ └───────────────────────┘ └─────────────────────┘ ``` - **引擎操作**（容器、镜像、统计信息、日志、系统信息）使用Docker引擎API通过[`dockerode`](https://github.com/apocas/dockerode)。 - **Compose操作**调用官方的`docker compose` CLI，使用**无shell**、完全参数引用的spawn（无字符串插值，无注入面）。 - **stdout是神圣的**：它只承载JSON-RPC流。 每行日志都输出到**stderr**。 --- ## ✅ 需求 | 需求 | 备注 | | --- | --- | | **Node.js ≥ 18** | ES模块 + 现代API。 推荐Node 20+。 | | **可达的Docker引擎** | 默认情况下为本地套接字；支持远程TCP/TLS。 | | **`docker` CLI在`PATH`上** | 仅需用于**Compose**工具。 洞察/生命周期工具无需它。 | | **MCP客户端** | Claude Desktop，Cursor，Continue，Zed或MCP Inspector。 | --- ## 📦 安装 ```bash # 1. 克隆 git clone https://github.com/<your-user>/docker-mcp-server.git cd docker-mcp-server # 2. 安装依赖 npm install # 3. 构建到dist/ npm run build ``` 使用官方MCP Inspector进行快速测试（无需AI客户端）： ```bash npm run inspect ``` 这将打开一个UI，您可以在其中列出工具并手动调用它们 - 在连接AI助手之前验证Docker连接非常完美。 --- ## 🔌 连接到您的AI客户端 ### Claude Desktop 编辑Claude Desktop配置文件： - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json` - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json` ```jsonc { "mcpServers": { "docker": { "command": "node", "args": ["/absolute/path/to/docker-mcp-server/dist/index.js"], "env": { "DOCKER_MCP_READONLY": "false", "DOCKER_MCP_ALLOW_EXEC": "false", "DOCKER_MCP_DEFAULT_LOG_TAIL": "200" } } } } ``` > 一个现成的副本位于 [`examples/claude_desktop_config.json`](./examples/claude_desktop_config.json)。 重启Claude Desktop并询问：**“正在运行哪些容器？”** - 助手将代表**SoyRage Agency**问候您并继续。 ### Cursor / Continue / Zed 任何支持MCP的客户端都以相同的方式工作 - 注册一个stdio服务器，其命令是`node`，其参数是`dist/index.js`的绝对路径，并传递相同的环境变量。 请参阅您客户端的MCP文档以获取确切的配置位置； 服务器块是相同的。 --- ## ⚙️ 配置参考 每个设置都是一个环境变量。 自动加载本地 **`.env`**文件（位于`package.json`旁边）； 已经存在于进程环境中的值始终获胜，因此您的MCP客户端可以覆盖文件。 见 [`.env.example`](./.env.example) 获取注释模板。 | 变量 | 默认值 | 描述 | | --- | --- | --- | | `DOCKER_HOST` | 平台套接字 | 引擎端点。 接受 `unix:///var/run/docker.sock`， `npipe:////./pipe/docker_engine` 或 `tcp://host:port`。 空 = 平台默认值。 | | `DOCKER_CERT_PATH` | - | 包含 `ca.pem`， `cert.pem`， `key.pem` 的目录，用于TLS安全的远程守护进程。 | | `DOCKER_TLS_VERIFY` | `false` | `1`/`true` 验证守护进程证书（推荐用于远程主机）。 | | `DOCKER_MCP_READONLY` | `false` | 当 `true` 时， **所有** 状态更改工具都隐藏 - 服务器仅公开洞察。 | | `DOCKER_MCP_ALLOW_EXEC` | `false` | 当 `true` 时，注册 `exec_in_container` 工具（任意容器内命令）。 | | `DOCKER_MCP_CONTAINER_ALLOWLIST` | - | 服务器可以操作的容器 **名称或前缀** 的逗号分隔列表。 空 = 所有。 前缀匹配意味着 `web` 涵盖 `web-1`， `web-2`。 | | `DOCKER_MCP_DEFAULT_LOG_TAIL` | `200` | `container_logs` 在省略 `tail` 时返回的默认日志行数。 | | `DOCKER_MCP_COMPOSE_CWD` | 进程cwd | 用于解析 **相对** Compose文件路径的基本目录。 | | `DOCKER_MCP_LOG_LEVEL` | `info` | 写入stderr的诊断详细程度： `debug` \| `info` \| `warn` \| `error`。 | | `DOCKER_MCP_PLUGINS` | - | 仅加载 **这些** 插件（逗号分隔）。 空 = 所有。 | | `DOCKER_MCP_DISABLED_PLUGINS` | - | 禁用这些插件（逗号分隔）。 `about` 已锁定。 | | `DOCKER_MCP_PANEL_HOST` | `127.0.0.1` | 交互式面板的绑定地址。 | | `DOCKER_MCP_PANEL_PORT` | `4600` | 交互式面板的端口。 | | `DOCKER_MCP_PANEL_DEMO` | `false` | 在面板/TUI中提供虚拟演示数据。 | | `DOCKER_MCP_PANEL_METRICS` | `true` | 公开Prometheus `/metrics` 端点。 | | `DOCKER_MCP_PANEL_TERMINAL` | `true` | 启用面板内的命令终端。 | | `DOCKER_MCP_BACKUP_DIR` | `./snapshots` | 容器快照/导出的目录。 | | `DOCKER_MCP_BACKUP_WEBHOOK` | - | 每次备份后调用的Webhook（电子邮件/云桥）。 | | `DOCKER_MCP_AI_ENDPOINT` | - | AI副驾驶的OpenAI兼容基准URL（空 = 关闭）。 | | `DOCKER_MCP_AI_KEY` | - | AI端点的Bearer密钥。 | | `DOCKER_MCP_AI_MODEL` | `gpt-4o-mini` | AI端点的模型名称。 | | `DOCKER_MCP_CONFIG` | `docker-mcp.config.json` | 可选JSON配置文件路径。 | **布尔解析：** 任意 `1`， `true`， `yes`， `on`（不区分大小写）均计为真。 JSON **配置文件** 为上述所有文件提供默认值 - 请参阅 [配置文件](#config-file)。 --- ## 🌐 连接到远程/TLS守护进程 通过将 `DOCKER_HOST` 指向其TCP端点来管理Docker主机。 对于除 `localhost` 之外的任何主机， **始终** 使用TLS。 ```bash # 普通TCP（仅限受信任的网络） DOCKER_HOST=tcp://192.168.1.50:2375 # 使用相互TLS加密的TCP DOCKER_HOST=tcp://docker.internal:2376 DOCKER_TLS_VERIFY=1 DOCKER_CERT_PATH=/home/you/.docker/certs ``` 启用TLS时，服务器读取 `ca.pem`， `cert.pem` 和 `key.pem` 文件，并通过HTTPS（默认端口 `2376`；普通TCP默认为 `2375`）连接到守护进程。 --- ## 🛡️ 安全模型 此服务器可以控制您的基础设施，因此它具有防御深度默认值。 **您**决定授予多少权限。 | 控制 | 它做什么 | 推荐用于 | | --- | --- | --- | | **只读模式** (`DOCKER_MCP_READONLY=true`) | 隐藏每个状态更改工具。 模型实际上看不到 `stop`， `remove`， `deploy_stack` 等。 | 演示，仪表板，生产洞察。 | | **容器允许列表** (`DOCKER_MCP_CONTAINER_ALLOWLIST`) | 将 **所有** 容器工具限制为匹配的名称/前缀。 其他容器返回一个明确的“不允许”错误。 | 多租户主机，“管理应用程序，永远不要管理数据库”。 | | **选择性执行** (`DOCKER_MCP_ALLOW_EXEC`) | 强大的 `exec_in_container` 工具 **未注册** 除非您启用它。 | 保持禁用，除非您特别需要它。 | | **无shell Compose** | Compose命令作为参数数组生成 - 无shell，无插值。 | 始终开启。 | | **温和错误** | 失败的工具返回一个 `isError` 文本结果，而不是崩溃传输，因此错误的调用永远不会使会话崩溃。 | 始终开启。 | ### 安全配方 ```bash # 提供一个具有零风险的实时演示 DOCKER_MCP_READONLY=true # 让AI仅管理应用层，绝不管理数据存储 DOCKER_MCP_CONTAINER_ALLOWLIST=web,api,worker # 绝不允许进入容器shell（这是默认值） DOCKER_MCP_ALLOW_EXEC=false ``` > ⚠️ **最小特权原则。** 从只读开始，添加允许列表，并且只有在您信任设置时才启用写入/执行。 将助手视为一个非常快速的初级工程师：有帮助，但您对破坏性的操作进行签发。 --- ## 🧰 完整的工具参考 标记为 **W** 的工具会更改状态，当 `DOCKER_MCP_READONLY=true` 时会被 **隐藏**。 `exec_in_container` 除非启用 `DOCKER_MCP_ALLOW_EXEC=true`，否则也会被隐藏。 ### 身份 | 工具 | 参数 | 描述 | | --- | --- | --- | | `about` | - | 返回SoyRage Agency欢迎横幅、积分和许可证。 助手使用它来介绍服务器。 | | `list_plugins` | - | 列出模块化功能插件以及每个插件是否启用。 | ### 洞察（只读） | 工具 | 参数 | 描述 | | --- | --- | --- | | `list_containers` | `all?: boolean` | 列出具有状态、镜像、状态和已发布端口的容器。 `all` 包括已停止的容器。 | | `inspect_container` | `container: string` | 一个容器的完整底层配置（env、挂载、网络、重启策略、健康）以及可读的摘要。 | | `container_stats` | `container: string` | 实时CPU %、内存使用/限制和网络RX/TX的快照。 | | `container_logs` | `container: string`， `tail?: number`， `since?: string`， `timestamps?: boolean` | 尾部stdout/stderr。 `since` 接受Unix时间戳或相对值，如 `10m`， `2h`， `1d`。 Docker流头部自动解复用。 | | `list_images` | - | 具有 `repo:tag`、短ID、大小和年龄的本地缓存镜像；以及总磁盘占用空间。 | | `system_info` | - | 引擎版本、主机OS/架构、内核、CPU/RAM、存储驱动和对象计数。 | | `disk_usage` | - | 跨镜像/容器/卷的可回收空间（`docker system df`）。 | | `list_networks` | - | 具有驱动程序和范围的网络。 | | `list_volumes` | - | 具有驱动程序和挂载点的命名卷。 | ### Compose — 只读 | 工具 | 参数 | 描述 | | --- | --- | --- | | `compose_ps` | `file: string`， `project?: string` | 列出一个栈的服务及其状态/健康状况。 `file` 是compose文件 **或** 包含一个目录。 | | `compose_config` | `file`， `project?` | 验证并渲染完全解析的Compose配置（非零结果意味着文件有错误）。 | ### 生命周期（**W**） | 工具 | 参数 | 描述 | | --- | --- | --- | | `start_container` | `container` | 启动已停止的容器（如果已经运行则无操作）。 | | `stop_container` | `container`， `timeout?: number` | 正常停止（SIGTERM → SIGKILL超时秒数，默认为10）。 | | `restart_container` | `container`， `timeout?: number` | 重启容器。 | | `remove_container` | `container`， `force?: boolean`， `removeVolumes?: boolean` | 删除容器。 破坏性；如果正在运行则需要 `force`。 | | `exec_in_container` | `container`， `command: string[]`， `workdir?: string` | 在正在运行的容器内运行一次性命令（参数数组，无shell）。 **仅需选择**。 | ### Compose — 状态更改（**W**） | 工具 | 参数 | 描述 | | --- | --- | --- | | `deploy_stack` | `file`， `project?`， `build?: boolean`， `services?: string[]` | `docker compose up -d --remove-orphans` - 部署/刷新栈，可选重建并限定服务。 | | `compose_down` | `file`， `project?`， `removeVolumes?: boolean` | 停止并删除栈。 `removeVolumes` 也会删除命名卷（破坏性）。 | | `compose_restart` | `file`， `project?`， `services?: string[]` | 重启所有或选定的服务。 | | `compose_pull` | `file`， `project?`， `services?: string[]` | 拉取栈的最新镜像（与 `deploy_stack` 结合使用进行滚动更新）。 | --- ## 💬 示例对话 自然语言提示和模型通常会调用的工具： | 您说… | 助手调用… | | --- | --- | | “现在正在运行什么？” | `list_containers` | | “显示所有内容，包括已停止的。” | `list_containers { all: true }` | | “为什么 `api` 崩溃了？ 最后100行。” | `container_logs { container: "api", tail: 100 }` | | “ `web` 日志中过去15分钟内有什么？” | `container_logs { container: "web", since: "15m" }` | | `db` 是否占用大量内存？ | `container_stats { container: "db" }` | | “重启 `nginx`。” | `restart_container { container: "nginx" }` | | “部署 `./prod` 栈并重建。” | `deploy_stack { file: "./prod", build: true }` | | `./prod` 栈中哪些服务已启动？ | `compose_ps { file: "examples/demo-stack" }` | | Docker 使用多少磁盘？ | `disk_usage` | | “谁构建了这个集成？” | `about` | 想要一个栈进行练习？ [`examples/demo-stack/compose.yaml`](./examples/demo-stack/compose.yaml) 启动 **nginx + redis**。 试试： *“部署演示栈，然后显示其服务及其日志。”* --- 🗂️ 项目结构 ``` docker-mcp-server/ ├── assets/ │ ├── soyrage-banner.svg # SoyRage Agency 标识 banner（此 README） │ └── screenshots/ 添加水印的面板截图 ├── examples/ │ ├──_desktop_config.json │ ├── docker-mcp.config.json # 可复制的配置文件示例 │ └── demo-stack/ │ └── compose.yaml # nginx + redis playground ├── install.sh / install.ps1 # 适用于初学者的一键式引导 ├── scripts/ │ ├── install.mjs # 跨平台 Claude Desktop 配置器 │ ├── copy-public.mjs # 在构建后将面板资产复制到 dist/ │ ├── shots.mjs # 重新生成面板截图（Playwright） │ └── tui-shot.mjs # 渲染 TUI 为 PNG（ANSI→HTML→Playwright） ├── src/ │ ├── index.ts # MCP 入口点：banner、归属保护、线路连接 │ ├── branding.ts # SoyRage 标识、ASCII 横幅、MCP 说明 │ ├── plugins.ts # 模块化插件目录和选择加载器 │ ├── config.ts # 分层配置（默认值 → 文件 → .env → 环境变量） │ ├── logger.ts # 仅 stderr 结构化日志记录器（stdout 是神圣的） │ ├── docker/ │ │ ├── client.ts # 类型安全的 dockerode 包装器 + 允许列表强制执行 │ │ └── compose.ts # 安全、无 shell 的 `docker compose` 驱动程序 │ ├── tools/ # 每个插件一个模块的工具 │ │ ├── context.ts # 共享依赖包 + 插件元数据 │ │ ├── about.ts # 关于 / 列出插件（标识、锁定） │ │ ├── containers.ts # 列出 / 检视 / 统计 │ │ ├── logs.ts # 日志跟踪与流分离 │ │ ├── lifecycle.ts # 启动 / 停止 / 重启 / 删除 /│ │ ├── images.ts # 镜像库存 │ ├── system.ts 系统信息 / 磁盘使用情况 / 网络 / 卷 │ │ └── compose.ts # 部署 / 关闭 / / 拉取 / 进程 / 配置 │ ├── panel/ # 交互式 Web 仪表盘 │ │ ├── index.ts # 面板入口点（docker-mcp-panel 二进制文件） │ │ ├── server.ts # Node 核心 HTTP 服务器 + REST API + /metrics │ │ service.ts # UI/监控数据层，统计和 Prometheus │ │ └── public/ # 手工编写的 SPA（index.html，styles.css，app.js） │ ├── tui/ # 终端 UI（docker-mcp-tui 二进制文件） │ │ index.ts # TUI 入口点（+ --frame/--splash 快│ │ ├── app.ts # 交互式应用程序：欢迎，仪表盘，键处理 │ │ ├── # 圆角框渲染器 │ │ └── ansi.ts # ANSI 颜色，游标控制，宽度感知填充 │ └── utils/ │ ├── format.ts # 表格，字节和时间人性化 │ └── result.ts # MCP 结果助手 + 错误保护 ├── docker-mcp.config.json # （可选）您的配置文件 ├── .env.example # 注释配置模板 ├── LICENSE # SoyRage 归属许可 ├── NOTICE # 归属通知 └── README.md ``` --- ## 🧠 设计原则 1. **stdout 保留** 用于 JSON-RPC 协议流；所有诊断信息都输出到 **stderr**。违反此规则会破坏 MCP 连接 — 日志记录器强制执行此规则。 2. **无 shell 插值**。Compose 命令使用参数数组生成，而不是 shell 字符串，从而消除了命令注入风险。 3. **软故障**。抛出异常的处理程序返回一个干净的Error` 文本结果，模型可以读取并从中恢复，而不是破坏传输。 4. **每个模块一个关注点**。工具按功能分组；每个组是一个小而专注的文件，显式接收其依赖项（无全局变量）。 5. **依赖表面小**。手动编写的 `.env` 加载器保留 `dotenv`；只有 `@modelcontextprotocol/sdk`、`dockerode` 和 `zod` 是运行时依赖项。 6. **通过构造实现安全**。只读模式和允许列表在边界处检查，因此无法通过遗忘的分支绕过不安全的调用。 --- ## 🧪 开发 ```bash npm run dev # 使用 tsx 热重载 MCP 服务器 npm run typecheck # 严格的类型检查，无输出 npm run build # 编译到 dist/ 并复制面板资产 npm run start # 运行已编译的 MCP 服务器 npm run inspect # 启动 MCP 检查器，针对已编译的服务器 npm run panel # 运行交互式面板（带有 /metrics） npm run panel:dev # 使用 tsx 热重载面板 npm run panel:demo # 使用演示数据运行面板 npm run tui # 运行终端 UI npm run tui:demo # 使用演示数据运行终端 UI npm run shots 重新生成面板截图（需要 Playwright chromium） npm run clean # 删除 dist/ ``` **编码标准：** TypeScript `strict` 启用 `noUnusedLocals`、`noUnusedParameters`、`noImplicitReturns` 和 `noFallthroughSwitch`。每个源文件都带有 SoyRage Agency 归属头。 **持续集成：** [`.github/workflows/ci.yml`](./.github/workflows/ci.yml) 在每次推送/PR 上运行 — 安装、类型检查、构建，然后在无头演示面板上运行 **深度端到端套件**（`node scripts/deep-test.mjs`，**70 项）。在本地随时运行： ```bash npm run build DOCKER_MCP_PANEL_DEMO=true DOCKER_MCP_PANEL_PORT=4600 node dist/panel/index.js & node scripts/deep-test.mjs ``` --- ## 🩺 故障排除和常见问题 <details> <summary><b>“无法连接到 Docker 守护进程。”</b></summary> 服务器已启动但无法连接到 Docker。请检查： - Docker Desktop / 守护进程是否**正在运行**。 - `DOCKER 是否适用于您的平台（为空 = 默认套接字）。 - 在 Linux 上，您的用户可以访问套接字（`docker` 组）或您具有足够的权限。 服务器**继续，以便工具调用在您的聊天客户端内返回友好错误，而不是崩溃。 </details> <details> <summary><Compose 工具返回“未在 PATH 上找到 `docker` CLI。”</b></summary> Compose 工具外壳docker compose`。请安装 Docker Desktop 或 `docker-compose-plugin`，并确保 `docker` 位于您的环境中 MCP 客户端启动服务器的 `PATH` 中。 </details> <details> <summary><b>助手无法看到我的编写工具。</b></summary> 您可能处于只读模式。请设置 `DOCKER_MCP_READONLY=false`（默认值），然后重启 客户端，以便它重新读取工具列表。 </details> <summary><b>容器“未被允许列表覆盖”。</b></summary> `DOCKER_MCP_CONTAINER_ALLOWLIST` 已设置，但目标不匹配。请将其名称/前缀添加到，或清除变量以允许所有。 </details> <details> <summary><b>我的数据是否被发送到其他</b></summary> 否。此服务器仅与您的 Docker进程和您的 MCP 客户端通过本地标准输入/通信。它不会进行任何网络调用。 </details> 🗺️ 路线图 - [x] 具有实时监控和历史图表的交互式 Web 面板 - [x] 创意终端 UI（TUI） x] Prometheus `/metrics` 端点（Prometheus 就绪） - [x] AI 驱动的终端和文件编辑（兼容 OpenAI） - [x] 一键安装程序 + CI（构建/类型检查/70 次检查端到端） - [ ] 带有服务器端进度报告的 `follow_logs` 流 - [ ] 具有进度报告的镜像拉取/构建工具 - [ ] 在显式确认后，修剪工具（`docker system prune`）被闸门保护 - [ ] 用于只读容器/堆栈快照的 MCP **资源** - [ ] 原生 直接 S3/Drive 备份目标 - [ ] 用于单行 `npx` 使用的已发布 npm 包 欢迎提出想法和 PR — 请参见下文。 --- ## 🤝 贡献 欢迎贡献！请： 1. 在大型 PR 之前打开问题描述更改。 2. 保持 **仅 stderr 日志记录** 和 **无 shell Compose** 不变. 保留 **SoyRage Agency** 属性头标识（这是许可证要求. 在提交前运行 `npm run typecheck && npm run build`。 --- ## 🏢 关于 SoyRage Agency <div align="center"> <a href="https://soyrage.es/"><img src="./assets/soyrage-banner.svg" alt="SoyRage Agency" width="88%"></a> </div> **SoyRage Agency** 是一家位于**西班牙瓦伦西亚**的全栈开发和基础设施工作室，致力于打造 **DevOps 与 AI 相遇** 的工具。我们为开发者和自托管社区打造精致、绪的软件。 - 🌐 网站：**[soyrage.es](https://soyrage.es/)** - 🧑‍💻 专注：全栈开发 · 基础设施工程 · AI 工具 - 📫 与我们合作：**[soyrage.es](https://soyrage.es/)** 如果这个项目对您有帮助，在存储库上加 ⭐ 并链接回 **[soyrage.es](https://soyrage.es 真诚地帮助我们继续开放开发。谢谢！ --- ## 💙 支持项目 Docker MCP 服务器由 **SoyRage Agency** 在开放状态下构建。如果它节省了您的时间或在工作中使用，请考虑支持持续开发 — 它直接资助新功能（原生 SMTP/S3 备份、、更多集成）并免费。 <div align="center"> [](https://www.paypal.com/paypalme/soyrageagency) /soyrageagency** · 在存储库上 也很有帮助！ </div> 其他帮助方式：到 r/selfhosted，报告问题，，或聘请 [SoyRage Agency](https://.es/) 进行自定义 + AI 工具开发。 --- ## 🖋️ 致谢与许可 ="center"> **由 [SoyRage Agency://soyrage.es/) 设计、构建和维护 —rage.es/** </div> 该项目在 **SoyRage 归属许可** 下发布（参见 [`LICENSE`](./LICENSE) 和 [`NOTICE`](./NOTICE)）。您可以自由使用、修改和自我托管 — SoyRage Agency 的署名保持可见**：源代码头、`package.json` 作者字段和运行时标识（ASCII 横幅、`about` 工具和 MCP `instructions`）必须保持完整。 > ℹ️ **关于克隆”：** 在您的机器上运行的软件始终可以被修改 — 这不是 DRM。归属已在默认情况下在所有地方嵌入，以便删除它是一个刻意的行为，而许可证使该行为成为违反行为。对于白标或商业许可证，请通过 **[soyrage.es](https://.es/)** 联系我们。 <div align="center"> **© 2026 SoyRage Agency — https://soyrage.es/** 在西班牙瓦伦西亚用 ❤ 制作。 </div>