Komodo MCP Server

MCP Komodo

适用于 Komodo DevOps 平台的 MCP 服务。通过 Cursor、Claude Code 和 Claude Desktop 中的自然语言管理服务器、堆栈、部署、构建等。

功能

• 覆盖完整 Komodo DevOps API 的 63 个工具，分为 14 个类别
• 提供 三种访问级别（read-only、read-execute、full），实现精细控制
• 通过 KOMODO_CATEGORIES 筛选类别，只开放所需工具
• 零 HTTP 依赖——轻量级原生 fetch 客户端，无需 SDK
• 在 GHCR 上提供适用于 linux/amd64 和 linux/arm64 的 Docker 镜像
• 使用 Streamable HTTP 协议，通过 HTTP 传输提供 远程 MCP（MCP_TRANSPORT=http）
• 使用 TypeScript/ESM，提供完整的类型安全

API 兼容性

适用于 Komodo 1.19.5。

快速开始

使用 npx 直接运行服务：

KOMODO_URL="https://komodo.example.com" \
KOMODO_API_KEY="your-api-key" \
KOMODO_API_SECRET="your-api-secret" \
npx -y @samik081/mcp-komodo

服务启动时会验证与 Komodo 的连接；如果凭据缺失或无效，会立即退出并显示清晰的错误信息。

Docker

使用 Docker 运行（stdio 传输，与 npx 相同）：

docker run --rm -i \
  -e KOMODO_URL=https://komodo.example.com \
  -e KOMODO_API_KEY=your-api-key \
  -e KOMODO_API_SECRET=your-api-secret \
  ghcr.io/samik081/mcp-komodo

要通过 HTTP 传输将其作为远程 MCP 服务运行：

docker run -d -p 3000:3000 \
  -e MCP_TRANSPORT=http \
  -e KOMODO_URL=https://komodo.example.com \
  -e KOMODO_API_KEY=your-api-key \
  -e KOMODO_API_SECRET=your-api-secret \
  ghcr.io/samik081/mcp-komodo

MCP 端点位于 http://localhost:3000，健康检查端点位于 http://localhost:3000/health。

配置

Claude Code CLI（推荐）：

# Using npx
claude mcp add --transport stdio komodo \
  --env KOMODO_URL=https://komodo.example.com \
  --env KOMODO_API_KEY=your-api-key \
  --env KOMODO_API_SECRET=your-api-secret \
  -- npx -y @samik081/mcp-komodo

# Using Docker
claude mcp add --transport stdio komodo \
  --env KOMODO_URL=https://komodo.example.com \
  --env KOMODO_API_KEY=your-api-key \
  --env KOMODO_API_SECRET=your-api-secret \
  -- docker run --rm -i ghcr.io/samik081/mcp-komodo

# Using remote HTTP (connect to a running Docker container or HTTP server)
claude mcp add --transport http komodo http://localhost:3000

JSON 配置（适用于 Claude Code .mcp.json、Claude Desktop claude_desktop_config.json、Cursor .cursor/mcp.json）：

{
  "mcpServers": {
    "komodo": {
      "command": "npx",
      "args": ["-y", "@samik081/mcp-komodo"],
      "env": {
        "KOMODO_URL": "https://komodo.example.com",
        "KOMODO_API_KEY": "your-api-key",
        "KOMODO_API_SECRET": "your-api-secret"
      }
    }
  }
}

Docker（stdio）：

{
  "mcpServers": {
    "komodo": {
      "command": "docker",
      "args": ["run", "--rm", "-i",
        "-e", "KOMODO_URL=https://komodo.example.com",
        "-e", "KOMODO_API_KEY=your-api-key",
        "-e", "KOMODO_API_SECRET=your-api-secret",
        "ghcr.io/samik081/mcp-komodo"
      ]
    }
  }
}

远程 MCP（连接到正在运行的 Docker 容器或 HTTP 服务）：

{
  "mcpServers": {
    "komodo": {
      "type": "streamable-http",
      "url": "http://localhost:3000"
    }
  }
}

访问级别

使用 KOMODO_ACCESS_TIER 环境变量控制可用工具：

级别	工具	说明
full（默认）	63	读取、执行和写入——完全控制
read-execute	55	读取和执行——不能创建或删除资源，也不能管理用户
read-only	39	只读——可安全探索，不会更改状态

级别详情：

• full：全部 63 个工具。包括用于创建、更新和删除 Komodo 资源的 komodo_write_resource，以及用户管理工具（服务用户、API 密钥、权限）。
• read-execute：55 个工具。所有读取工具，以及执行工具（部署、拉取、生命周期、运行等）。komodo_write_resource 工具和用户管理写入工具不可见。
• read-only：39 个工具。仅包括列表、获取、日志、检查、统计、摘要、操作历史，以及读取用户和权限的工具。所有执行和写入工具均不可见。

在你的级别中不可用的工具不会注册到 MCP 服务中。它们不会出现在 AI 工具的工具列表中，从而保持上下文整洁。

将 KOMODO_ACCESS_TIER 设为 read-only、read-execute 或 full（默认值：full）。

环境变量

变量	必需	默认值	描述
KOMODO_URL	是	--	Komodo Core 实例的 URL
KOMODO_API_KEY	是	--	用于身份验证的 API 密钥
KOMODO_API_SECRET	是	--	用于身份验证的 API 密钥
KOMODO_ACCESS_TIER	否	full	访问级别：read-only、read-execute 或 full
KOMODO_CATEGORIES	否	(all)	以逗号分隔的类别允许列表（例如，servers,stacks,builds）
KOMODO_TOOL_BLACKLIST	否	(none)	以逗号分隔的要排除的工具名称列表（例如，komodo_destroy_stack）
KOMODO_TOOL_WHITELIST	否	(none)	以逗号分隔的强制包含工具名称列表，可绕过访问级别和类别筛选
KOMODO_ALLOW_ENV_VALUES	否	(tier-based)	检查工具是否可以通过 show_env_values: true 返回明文环境变量值。默认情况下，read-execute/full 允许，read-only 拒绝；可设置为 true 或 false 进行覆盖
DEBUG	否	false	启用调试日志并输出到 stderr
MCP_TRANSPORT	否	stdio	传输模式：stdio（默认）或 http
MCP_PORT	否	3000	HTTP 服务端口（仅在 MCP_TRANSPORT=http 时使用）
MCP_HOST	否	0.0.0.0	HTTP 服务绑定地址（仅在 MCP_TRANSPORT=http 时使用）
MCP_SESSION_IDLE_TIMEOUT	否	1800	HTTP 会话关闭并释放其内存前的空闲秒数（拥有已连接 SSE 流的会话不会关闭）。设为 0 可禁用。仅在 MCP_TRANSPORT=http 时使用
MCP_EXCLUDE_TOOL_TITLES	否	false	设为 true 可在注册时省略工具标题（节省令牌）

在 Komodo UI 的 Settings > API Keys 中生成 API 密钥。

可用类别

servers、stacks、deployments、containers、builds、repos、procedures、actions、builders、alerters、resource-syncs、updates、users、write

工具

mcp-komodo 提供 63 个按类别组织的工具。每个工具的 Access 列显示所需的最低级别：read-only（所有级别均可用）、read-execute（需要 read-execute 或 full）或 full（仅需要 full 级别）。Hints 列显示工具行为：read-only（不更改状态）、destructive（修改现有状态）、idempotent（调用两次结果相同）。

默认情况下，所有 16 个执行工具都会等待操作完成并报告实际结果；传入 wait: false 可改为立即返回，或传入 wait_timeout_seconds 限制等待时间（默认值为 45s）。

服务（10 个工具）

| 工具 | 描述 | 访问权限 | 提示 | |------|-------------|--------|-------| | `komodo_list_servers` | 列出所有服务器及其状态和区域 | 只读 | 只读、幂等 | | `komodo_get_server` | 获取服务器配置、状态和操作状态 | 只读 | 只读、幂等 | | `komodo_get_server_stats` | 获取 CPU、内存、磁盘使用情况和平均负载 | 只读 | 只读、幂等 | | `komodo_get_server_info` | 获取操作系统详情、硬件信息和运行中的进程 | 只读 | 只读、幂等 | | `komodo_inspect_docker_container` | 检查 Docker 容器（`docker inspect` 负载）；除非设置 `show_env_values: true`，否则环境变量值会显示为 `sha256:<12-hex>` 摘要（`read-only` 层级下会拒绝此操作，除非设置 `KOMODO_ALLOW_ENV_VALUES=true`）——脱敏仅覆盖 `Env` 数组，因此标签、cmd 和挂载信息会以未脱敏形式返回 | 只读 | 只读、幂等 | | `komodo_inspect_docker_image` | 检查 Docker 镜像（`docker image inspect` 负载）；除非设置 `show_env_values: true`，否则镜像内置的环境变量值会显示为 `sha256:<12-hex>` 摘要（`read-only` 层级下会拒绝此操作，除非设置 `KOMODO_ALLOW_ENV_VALUES=true`）——脱敏仅覆盖 `Env` 数组，因此标签、cmd 和层信息会以未脱敏形式返回 | 只读 | 只读、幂等 | | `komodo_inspect_docker_network` | 检查 Docker 网络（等同于 docker network inspect） | 只读 | 只读、幂等 | | `komodo_inspect_docker_volume` | 检查 Docker 卷（等同于 docker volume inspect） | 只读 | 只读、幂等 | | `komodo_prune_docker` | 清理服务器上未使用的 Docker 资源 | 读写 | 破坏性、幂等 | | `komodo_delete_docker_resource` | 删除指定的 Docker 镜像、卷或网络 | 读写 | 破坏性 |

堆栈（10 个工具）

工具	描述	访问权限	提示
komodo_list_stacks	列出所有堆栈及其状态、服务器和服务数量	只读	只读、幂等
komodo_get_stack	获取堆栈配置、服务和操作状态	只读	只读、幂等
komodo_list_stack_services	列出堆栈中的服务及其镜像、容器状态和更新可用性	只读	只读、幂等
komodo_get_stacks_summary	获取按状态汇总的所有堆栈数量	只读	只读、幂等
komodo_get_stack_log	获取堆栈服务的日志，可选择搜索	只读	只读、幂等
komodo_inspect_stack_container	检查堆栈中特定服务的容器（docker inspect 负载）；除非设置 show_env_values: true，否则环境变量值会显示为 sha256:<12-hex> 摘要（read-only 层级下会拒绝此操作，除非设置 KOMODO_ALLOW_ENV_VALUES=true）——脱敏仅覆盖 Env 数组，因此标签、cmd 和挂载信息会以未脱敏形式返回	只读	只读、幂等
komodo_deploy_stack	部署或重新部署堆栈	读写	破坏性
komodo_pull_stack	拉取最新镜像但不重新部署（docker compose pull）	读写	幂等
komodo_stack_lifecycle	启动、停止、重启、暂停或取消暂停堆栈；可选择仅对指定服务执行操作	读写	破坏性
komodo_destroy_stack	永久销毁堆栈	读写	破坏性

部署（9 个工具）

| 工具 | 描述 | 访问权限 | 提示 | |------|-------------|--------|-------| | `komodo_list_deployments` | 列出所有部署及其状态、镜像和服务 | 只读 | 只读、幂等 | | `komodo_get_deployment` | 获取部署配置、容器状态和操作状态 | 只读 | 只读、幂等 | | `komodo_get_deployments_summary` | 按状态汇总所有部署的数量 | 只读 | 只读、幂等 | | `komodo_get_deployment_log` | 获取容器日志，可选择搜索 | 只读 | 只读、幂等 | | `komodo_inspect_deployment_container` | 检查部署的容器（`docker inspect` 负载）；除非设置 `show_env_values: true`，否则环境变量值会显示为 `sha256:<12-hex>` 摘要（在 `read-only` 层级下会拒绝此请求，除非设置 `KOMODO_ALLOW_ENV_VALUES=true`）——脱敏仅适用于 `Env` 数组，因此标签、cmd 和挂载内容会以未脱敏形式返回 | 只读 | 只读、幂等 | | `komodo_deploy_deployment` | 使用最新镜像和配置进行部署 | 读写 | 破坏性操作 | | `komodo_pull_deployment` | 拉取最新镜像，但不重新部署（docker pull） | 读写 | 幂等 | | `komodo_deployment_lifecycle` | 启动、停止、重启、暂停或取消暂停部署 | 读写 | 破坏性操作 | | `komodo_destroy_deployment` | 永久销毁部署 | 读写 | 破坏性操作 |

容器（1 个工具）

工具	描述	访问权限	提示
komodo_get_container_log	获取服务器上任意 Docker 容器的日志	只读	只读、幂等

构建（4 个工具）

工具	描述	访问权限	提示
komodo_list_builds	列出所有构建配置及版本信息	只读	只读、幂等
komodo_get_build	获取构建配置、构建器和操作状态	只读	只读、幂等
komodo_run_build	运行构建以创建 Docker 镜像	读写	—
komodo_cancel_build	取消正在运行的构建	读写	破坏性操作、幂等

仓库（3 个工具）

工具	描述	访问权限	提示
komodo_list_repos	列出所有仓库及其 URL、服务和状态	只读	只读、幂等
komodo_get_repo	获取仓库配置、分支和操作状态	只读	只读、幂等
komodo_repo_clone_pull	在目标服务器上克隆或拉取仓库	读写	破坏性操作

流程（3 个工具）

工具	描述	访问权限	提示
komodo_list_procedures	列出所有流程及其状态	只读	只读、幂等
komodo_get_procedure	获取流程阶段、操作和操作状态	只读	只读、幂等
komodo_run_procedure	运行流程（执行所有阶段）	读写	破坏性操作

操作（3 个工具）

工具	描述	访问权限	提示
komodo_list_actions	列出所有操作及其状态	只读	只读、幂等
komodo_get_action	获取操作配置和操作状态	只读	只读、幂等
komodo_run_action	运行自定义 TypeScript/Deno 操作	读写	破坏性操作

构建器（2 个工具）

工具	描述	访问权限	提示
komodo_list_builders	列出所有构建器及其类型	只读	只读、幂等
komodo_get_builder	获取构建器类型、服务配置和状态	只读	只读、幂等

告警器（2 个工具）

| 工具 | 描述 | 访问权限 | 提示 | |------|-------------|--------|-------| | `komodo_list_alerters` | 列出所有告警器及其类型 | 只读 | 只读、幂等 | | `komodo_get_alerter` | 获取告警器的端点类型、配置和状态 | 只读 | 只读、幂等 |

资源同步（3 个工具）

工具	描述	访问权限	提示
komodo_list_resource_syncs	列出所有资源同步及其状态和仓库信息	只读	只读、幂等
komodo_get_resource_sync	获取同步配置、受管理的资源和状态	只读	只读、幂等
komodo_trigger_sync	从 Git 仓库触发 GitOps 同步	读取-执行	破坏性操作

更新（2 个工具）

工具	描述	访问权限	提示
komodo_list_updates	列出操作历史记录，可按资源类型、目标、操作和成功状态筛选	只读	只读、幂等
komodo_get_update	获取完整的操作详情，包括每个阶段的日志以及标准输出/标准错误	只读	只读、幂等

用户（10 个工具）

所有 10 个用户工具都需要 Komodo 管理员账户——无论配置的访问级别如何，Komodo 都会拒绝非管理员 API 密钥的请求。

工具	描述	访问权限	提示
komodo_list_users	列出 Komodo 用户，可选择按服务用户筛选	只读	只读、幂等
komodo_list_api_keys_for_service_user	列出服务用户的 API 密钥（不会返回密钥）	只读	只读、幂等
komodo_list_permissions	列出授予用户或用户组的权限	只读	只读、幂等
komodo_create_service_user	为自动化创建服务用户	完全访问	—
komodo_delete_user	按 ID 或用户名删除用户	完全访问	破坏性操作
komodo_create_api_key_for_service_user	为服务用户创建 API 密钥（密钥只会返回一次）	完全访问	—
komodo_delete_api_key_for_service_user	删除服务用户的 API 密钥	完全访问	破坏性操作
komodo_update_user_base_permissions	更新用户的启用 / 创建服务器 / 创建构建标记	完全访问	破坏性操作、幂等
komodo_update_permission_on_resource_type	设置用户或用户组对某一类型所有资源的基础权限	完全访问	破坏性操作、幂等
komodo_update_permission_on_target	设置用户或用户组对某个特定资源的权限	完全访问	破坏性操作、幂等

写入（1 个工具）

工具	描述	访问权限	提示
komodo_write_resource	创建、更新或删除任何 Komodo 资源	完全访问	破坏性操作

验证是否正常工作

配置好 MCP 客户端后，向你的 AI 助手提问：

“有哪些服务器已连接到 Komodo？”

如果连接正常，助手将调用 komodo_list_servers，并返回你的服务器及其当前状态和区域。

使用示例

配置完成后，可以用自然语言向 AI 工具提问：

• “列出我的所有服务及其状态” -- 调用 komodo_list_servers，显示每台服务的当前状态和区域。

• “prod-01 服务的 CPU 和内存使用情况如何？” -- 调用 komodo_get_server_stats，显示实时资源使用情况。

• “显示生产环境堆栈的日志” -- 调用 komodo_get_stack_log，检索堆栈中所有服务的近期日志输出。

• “部署前端堆栈” -- 调用 komodo_deploy_stack，使用当前配置重新部署堆栈。

• “前端堆栈为什么部署失败了？” -- 调用 komodo_list_updates 查找失败的部署，然后调用 komodo_get_update 显示包含 stdout/stderr 的完整日志。

• “拉取监控堆栈的最新镜像” -- 调用 komodo_pull_stack 下载更新后的镜像，而不重新部署。

• “创建名为 api-staging、镜像为 myapp:latest 的新部署” -- 调用 komodo_write_resource，在 Komodo 中创建新的 Deployment 资源。

故障排除

连接被拒绝

检查 KOMODO_URL 是否正确，以及运行 MCP 服务的环境能否访问 Komodo Core。服务会在启动时验证连接，因此如果启动成功，当时的 URL 就是有效的。

凭据无效 / 401 Unauthorized

确认 API 密钥和密钥值正确。检查密钥是否已在 Komodo UI 的 Settings > API Keys 中撤销或过期。

工具未显示

检查访问级别设置。在 read-only 模式下，仅注册 39 个工具；在 read-execute 模式下，注册 55 个工具。使用 full（或不设置 KOMODO_ACCESS_TIER）以启用全部 63 个工具。检查 KOMODO_CATEGORIES——只会注册所列类别中的工具。还要检查 stderr 输出，确认服务启动时没有错误。

开发

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode (auto-reload)
npm run dev

# Open the MCP Inspector for interactive testing
npm run inspect

许可证

MIT