Komodo MCP Server

---

功能

🛠️ 全面的基础设施控制

• 88 种工具，20 个类别 — 全生命周期管理容器、堆栈、部署、服务器、构建、仓库、流程、操作、告警器、Docker Swarm（Komodo v2）、变量、资源同步、更新历史、Docker 镜像/网络/卷检查、构建器、标签和 TOML 导出；涵盖从列出和检查到部署、构建、扩缩容和销毁的各项操作。
• 远程终端访问 — 在服务器、容器、部署和堆栈服务上执行命令，提供实时输出流、退出代码和进度报告。
• 日志搜索与分析 — 在容器中按模式搜索日志，并可配置尾部限制和匹配计数。

🔌 随处部署

• 多种传输方式 — 可流式传输的 HTTP（有状态）、带 TLS 的 HTTPS、旧版 SSE 和 stdio。同一服务，适用于任意客户端。
• 多平台 Docker — 提供适用于 amd64、arm64、arm/v7 和 arm/v6（Raspberry Pi）的生产就绪镜像。采用非 root、多阶段构建，并使用 tini init。
• 兼容任意 MCP 客户端 — Claude Desktop、VS Code / GitHub Copilot，或任何兼容 MCP 的工具。可通过 Docker、npx 或原生 Node.js 运行。

🔐 安全与身份验证

• 三种身份验证方式 — API Key/Secret（推荐）、用户名/密码或 JWT 令牌。所有方式都支持通过 *_FILE 变体使用 Docker secrets。
• 默认启用身份验证 — 在 HTTP 模式下，除非明确禁用，否则每位用户都使用本地登录。[komodo]` 全局连接在启动时配置一次（或通过环境变量配置），仅用于 stdio 或禁用身份验证的部署。
• 破坏性操作需确认 — 删除、销毁、清理和 Shell 执行操作都会先请求人工操作员明确批准（使用带确认复选框的 MCP elicitation）。无法提示用户的客户端将采用失败关闭策略；可通过 MCP_CONFIRM_DESTRUCTIVE / MCP_CONFIRM_FALLBACK 调整。
• 默认强化安全性 — 输入验证（Zod）、速率限制、DNS 重绑定防护、通过 Helmet 设置安全标头，以及集中式失败关闭密钥脱敏：每项工具结果（包括 exec 输出和检索到的日志）在到达客户端对话记录前，都会经过框架的脱敏边界 — 请参阅密钥脱敏。

⚡ 可靠性与运维

• 实时进度与取消 — 长时间运行的操作（部署、启动、停止）会实时报告进度。可通过 AbortSignal 在操作进行中随时取消。
• 自动重连 — 监控连接并自动恢复，同时采用指数退避。身份验证失败时会立即停止重试。
• 健康与就绪状态 — 提供适用于 Kubernetes 的 /health 和 /ready 端点。komodo_health_check 会报告服务版本、连接状态和身份验证状态。

基于 mcp-server-framework 构建 — 这是一个可用于生产环境的 TypeScript MCP 服务框架，支持结构化日志记录、OpenTelemetry 和会话管理。

可用工具（69）

Category	Tools
Configuration	komodo_health_check
Containers	komodo_container_list, komodo_container_inspect, komodo_container_logs, komodo_container_search_logs, komodo_container_action (start/stop/restart/pause/unpause)
Servers	komodo_server_list, komodo_server_info, komodo_server_stats, komodo_server_apply (create/update), komodo_server_delete, komodo_server_action (start_all/restart_all/pause_all/unpause_all/stop_all_containers, prune_*, delete_network/image/volume)
Stacks	komodo_stack_list, komodo_stack_info, komodo_stack_apply (create/update), komodo_stack_delete, komodo_stack_action (deploy/pull/start/restart/pause/unpause/stop/destroy)
Deployments	komodo_deployment_list, komodo_deployment_info, komodo_deployment_apply (create/update), komodo_deployment_delete, komodo_deployment_action (deploy/pull/start/restart/pause/unpause/stop/destroy)
Builds	komodo_build_list, komodo_build_info, komodo_build_action (run/cancel), komodo_build_logs, komodo_build_apply (create/update), komodo_build_delete
Repos	komodo_repo_list, komodo_repo_info, komodo_repo_action (clone/pull/build/cancel_build), komodo_repo_apply (create/update), komodo_repo_delete
Procedures	komodo_procedure_list, komodo_procedure_info, komodo_procedure_action (run), komodo_procedure_apply (create/update), komodo_procedure_delete
Actions	komodo_action_list, komodo_action_info, komodo_action_action (run/cancel), komodo_action_apply (create/update), komodo_action_delete
Alerters	komodo_alerter_list, komodo_alerter_info, komodo_alerter_apply (create/update), komodo_alerter_delete
Swarms	komodo_swarm_list, komodo_swarm_info, komodo_swarm_apply (create/update), komodo_swarm_delete, komodo_swarm_nodes_list, komodo_swarm_services_list, komodo_swarm_action (update_node/remove_nodes/remove_services/remove_stacks)
Resource Syncs	komodo_resource_sync_list, komodo_resource_sync_info, komodo_resource_sync_action (run/refresh), komodo_resource_sync_apply (create/update), komodo_resource_sync_delete
Variables	komodo_variable_list, komodo_variable_info, komodo_variable_apply (create/update — value/description/is_secret), komodo_variable_delete
Updates	komodo_update_list (filterable, paginated), komodo_update_info
Terminal	komodo_exec (target: server / container / deployment / stack_service)
API Keys	komodo_user_list_api_keys, komodo_user_create_api_key, komodo_user_delete_api_key
Docker	komodo_docker_image_list, komodo_docker_image_inspect, komodo_docker_image_history, komodo_docker_network_list, komodo_docker_network_inspect, komodo_docker_volume_list, komodo_docker_volume_inspect
Builders	komodo_builder_list, komodo_builder_info, komodo_builder_apply (create/update), komodo_builder_copy, komodo_builder_rename, komodo_builder_delete
Tags	komodo_tag_list, komodo_tag_info, komodo_tag_apply (create/update), komodo_tag_delete
TOML Export	komodo_toml_export_all, komodo_toml_export_resources

提示： 每个工具都带有 _meta.category（取值为 config、container、server、stack、deployment、build、repo、procedure、action、alerter、swarm、resource_sync、variable、update、terminal、user、docker、builder、tag、toml 之一）和一个 requiredScopes 数组（komodo:read / komodo:operate / komodo:admin），因此 MCP 客户端和网关可以按类别和三层 RBAC 过滤或限制工具。

限制工具范围（服务端）。 为缩短客户端的工具列表并降低其令牌成本，可通过三个可选环境变量精简服务注册的工具：MCP_TOOLS_ALLOWED_CATEGORIES（类别允许列表；未设置时表示全部）、MCP_TOOLS_EXCLUDED_CATEGORIES（排除整个类别）和 MCP_TOOLS_EXCLUDED_TOOLS（按名称排除工具，例如 komodo_exec）。请使用上方列出的确切类别字符串。精简后的工具不会出现在 tools/list 中，也无法调用。这仅会减少可用工具，不会暴露更多工具，也不会绕过身份验证或“开放时只读”的行为。

列表、信息和日志工具支持通过 { cursor, page_size } 进行游标分页（1–100，默认值为 25），并在有更多条目时返回 _meta.page.next_cursor。inspect、info、logs 和 search_logs 响应还会包含一个限定于当前会话的 ephemeral://... 资源链接，以便通过 resources/read 在带外获取大型负载；传入 inline_full: true 可强制内联完整内容。

快速开始

Docker Compose（HTTP 推荐）

将其部署为持久化 HTTP 服务，即可从任意 MCP 客户端连接。

mkdir komodo-mcp && cd komodo-mcp
curl -O https://raw.githubusercontent.com/MP-Tool/komodo-mcp-server/main/docker/compose.yaml
curl -O https://raw.githubusercontent.com/MP-Tool/komodo-mcp-server/main/docker/docker.env
cp docker.env .env  # Edit with your credentials
docker compose up -d

-> 完整 Docker 指南

Claude Desktop

将以下内容添加到 claude_desktop_config.json（Settings -> Developer -> Edit Config）：

"komodo-mcp-server": {
  "command": "docker",
  "args": [
    "run", "-i", "--rm",
    "-e", "KOMODO_URL=https://komodo.example.com:9120",
    "-e", "KOMODO_API_KEY=api-key",
    "-e", "KOMODO_API_SECRET=api-secret",
    "ghcr.io/mp-tool/komodo-mcp-server:latest"
  ]
}

-> 完整 Claude 指南

VS Code / GitHub Copilot

将以下内容添加到工作区中的 .vscode/mcp.json：

{
  "servers": {
    "Komodo MCP Server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "KOMODO_URL=https://komodo.example.com:9120",
        "-e", "KOMODO_API_KEY=api-key",
        "-e", "KOMODO_API_SECRET=api-secret",
        "ghcr.io/mp-tool/komodo-mcp-server:latest"
      ]
    }
  }
}

-> 完整 VS Code 指南 · Node.js / npx（无需 Docker） · 所有集成

使用

连接后，用自然语言向 Claude、Copilot 或任何兼容 MCP 的助手提问，它会选择相应工具。每条提示词触发的工具会显示在右侧：

提示词	调用的工具
“列出我的所有 Komodo 服务”	komodo_server_list
“显示 production-server 上的容器”	komodo_container_list
“启动 nginx 容器”	komodo_container_action (start)
“将 my-app 部署到 staging”	komodo_deployment_action (deploy)
“获取 dev-server 的统计信息”	komodo_server_stats
“上次部署为什么失败？”	komodo_update_list -> komodo_update_info
“持续查看 api 容器的日志”	komodo_container_logs

使用 MCP Inspector 测试

npx @modelcontextprotocol/inspector --url http://localhost:8000/mcp

Streamable HTTP 传输请使用 /mcp；旧版 SSE 传输（如果已启用）请使用 /sse。请根据你的设置调整主机和端口。

身份验证

有两个不同的层面——不要混淆：

1. 连接到 Komodo——服务器本身如何与 Komodo Core 通信。选择一种方法：

方法	环境变量	最适用场景
API Key（推荐）	KOMODO_API_KEY + KOMODO_API_SECRET	服务账户、自动化
用户名 / 密码	KOMODO_USERNAME + KOMODO_PASSWORD	交互式用户
JWT Token	KOMODO_JWT_TOKEN	基于浏览器的 SSO（OIDC、GitHub、Google OAuth）

始终需要设置 KOMODO_URL。所有凭据也支持通过 Docker secrets 使用 *_FILE 变体 （例如 KOMODO_API_KEY_FILE）。此共享连接用于 stdio 和开放（禁用身份验证） HTTP 模式。

2. 登录 MCP 服务的用户（HTTP/HTTPS）——自 1.5.0 起默认启用。每个人 使用自己的 Komodo 用户名和密码登录，并获得拥有各自权限的独立会话。使用 MCP_AUTH_ENABLED=false 将其关闭（此时开放的网络服务为只读）； stdio 是本地模式，始终不进行身份验证。

完整的配置参考（环境变量、配置文件、Docker secrets）请参阅**配置指南**。

故障排除

连接被拒绝 / 服务器无法连接到 Komodo。 检查 KOMODO_URL——其中需要包含协议、主机和 Komodo Core 端口（例如 https://komodo.example.com:9120）。在 Docker 内部，localhost 指向容器，而不是主机——请使用主机的 IP 或 Docker 网络别名。确认没有任何因素（防火墙、反向代理）阻止该端口。

客户端连接时出现 401 Unauthorized（HTTP）。 自 1.5.0 起，HTTP/HTTPS 的身份验证默认开启，因此客户端必须登录（通过浏览器使用 Komodo 用户名和密码登录）。请完成登录，或设置 MCP_AUTH_ENABLED=false 以在不启用身份验证的情况下运行。登录后仍出现 401，通常表示 Komodo 凭据错误或账户已停用。（stdio 是本地模式，始终不需要身份验证。）

工具列表中缺少工具。 有两种原因，且都是设计如此：

• 只读模式。 如果你在 HTTP/HTTPS 传输模式下禁用了身份验证（MCP_AUTH_ENABLED=false），那么对匿名调用者而言，服务器将处于只读状态——所有写入/执行/删除工具（包括 komodo_exec）都会被隐藏并拒绝调用。启用 [auth]（每用户登录）即可恢复这些工具。此模式启用时，启动日志会显示 READ-ONLY 提示。
• 工具范围筛选器。 MCP_TOOLS_ALLOWED_CATEGORIES、MCP_TOOLS_EXCLUDED_CATEGORIES 或 MCP_TOOLS_EXCLUDED_TOOLS 会筛除已注册的工具。取消设置这三个变量即可显示所有工具。无效的类别名称会被忽略，启动时会发出警告并列出有效类别。

免责声明

AI 工具（GitHub Copilot、Claude）是开发工作流的一部分，用于代码生成、架构探索和文档起草。所有代码和文档都经过人工审查，以确保质量、准确性，并符合既定的工程标准。

本软件依据 GPL-3.0 License 提供。如果你发现错误或有任何想法，欢迎提交 问题 或 贡献。

贡献

欢迎贡献！详情请参阅我们的贡献指南。

• 🐛 报告错误
• 💡 请求功能
• 🔧 提交 PR

开发

# Clone and install
git clone https://github.com/MP-Tool/komodo-mcp-server.git
cd komodo-mcp-server
npm install

# Build and run
npm run build
npm start

文档

指南	描述
配置	所有环境变量、配置文件格式、优先级链、Docker secrets
Docker 部署	Docker Compose 设置、运行状况检查、生产环境部署
客户端集成	Claude Desktop、VS Code、Node.js/npx 设置指南
贡献	开发环境设置、编码规范、PR 指南
安全	漏洞报告、安全最佳实践
更新日志	版本历史和发布说明

许可证

GPL-3.0 许可证——详情请参阅 LICENSE。

要求

• Komodo v2（Komodo Core 2.x；对于较旧的 Core，服务会拒绝执行 komodo_exec 等依赖版本的工具）
• Docker（用于容器化部署）或 Node.js 22+（用于原生安装）
• 有效的 Komodo 凭据（API Key/Secret、Username/Password 或 JWT Token）

安全

通过 GitHub 的私密漏洞报告功能报告安全漏洞（请参阅 SECURITY.md）。

破坏性操作确认： 默认情况下，破坏性工具（所有 *_delete 工具、komodo_exec、stack/deployment destroy、server stop_all/prune_*/delete_*、swarm remove_*，以及 procedure/action/resource-sync run）都需要人工操作员先通过 MCP elicitation 提示词进行批准——选择“accept”并勾选确认复选框，之后才会执行任何操作。默认情况下，无法提示的客户端（不支持 elicitation，或处于无状态 HTTP 模式）会被拒绝。可通过 MCP_CONFIRM_FALLBACK=allow（在这类客户端上发出警告后执行）或 MCP_CONFIRM_DESTRUCTIVE=false（禁用此功能）进行调整——这与客户端不支持 elicitation 的 stdio 设置有关。

密钥脱敏： 工具结果会持久化到 MCP 客户端的对话记录，并转发给模型提供商，因此每个工具结果在离开进程前，都会通过框架集中式的故障关闭清理边界——涵盖结构化资源配置（env 块、webhook_secret、passkey）、告警器 webhook URL、exec 输出，以及容器/构建/更新日志，也涵盖内联负载和卸载后的资源链接。此外，is_secret 变量值始终会被屏蔽，stack 会移除插值后的 deployed_config/deployed_contents。纵深防御仅尽力而为：启发式规则可捕获确定性的密钥格式，但无法识别任意内容。预期例外：komodo_user_create_api_key 会不经脱敏直接返回仅可使用一次的密钥。请参阅密钥脱敏。

最佳实践：

• 切勿提交凭据
• 使用环境变量
• 保持依赖项为最新版本
• 以非 root 用户身份运行（Docker 中的默认设置）

链接

• Komodo — 容器管理平台
• Komodo 文档 — 官方文档
• MCP 规范 — Model Context Protocol
• MCP Registry — MCP 服务注册表

---