helm-mcp

一个开源 MCP（Model Context Protocol）服务，可让 AI 助手全面访问 Helm——Kubernetes 包管理器。采用原生 Helm Go SDK 构建，在单个二进制文件中同时支持 Helm 3.x 和 4.x。

使用自然语言管理 Kubernetes 部署。
将 helm-mcp 连接到 Claude、Cursor、VS Code 或任何兼容 MCP 的客户端，即可通过对话安装 chart、管理 release、搜索仓库等。

---

目录

• 为什么选择 helm-mcp？
• 安装
• 快速开始
• MCP 客户端配置
• MCP 协议支持
• 可用工具
• 工具注解
• 结构化输出
• Helm CLI 覆盖范围
• Kubernetes 身份验证
• Helm 版本选择
• Python 包
• 弹性配置（Python）
• 响应负载管理
• 已知限制
• 安全
  • 身份验证（OIDC/OAuth2）
  • 代表用户（OBO）进行令牌交换
• 开发
• 架构
• 贡献
• 社区
• 许可证

为什么选择 helm-mcp？

• 46 个 MCP 工具，覆盖所有 Helm CLI 命令（不包括 shell 补全和帮助）
• 双 Helm SDK 支持——通过原生 Go SDK 支持 Helm v3 和 v4（非 CLI 包装器）
• 两种传输模式——stdio（默认）和 Streamable HTTP，默认无状态
• 适配云服务提供商——开箱即用，支持 EKS、GKE、AKS kubeconfig 格式
• 安全至上——Linux 进程强化、凭据内存清零、输入验证、防止路径遍历
• Python 包装器——基于 FastMCP 的代理，可自动发现所有工具
• 支持正向代理——遵循 HTTP_PROXY、HTTPS_PROXY、NO_PROXY

安装

预编译二进制文件

从 GitHub Releases 下载适用于你平台的最新版本：

# macOS (Apple Silicon)
curl -LO https://github.com/SCGIS-Wales/helm-mcp/releases/latest/download/helm-mcp-darwin-arm64
chmod +x helm-mcp-darwin-arm64
sudo mv helm-mcp-darwin-arm64 /usr/local/bin/helm-mcp

# macOS (Intel)
curl -LO https://github.com/SCGIS-Wales/helm-mcp/releases/latest/download/helm-mcp-darwin-amd64
chmod +x helm-mcp-darwin-amd64
sudo mv helm-mcp-darwin-amd64 /usr/local/bin/helm-mcp

# Linux (amd64)
curl -LO https://github.com/SCGIS-Wales/helm-mcp/releases/latest/download/helm-mcp-linux-amd64
chmod +x helm-mcp-linux-amd64
sudo mv helm-mcp-linux-amd64 /usr/local/bin/helm-mcp

# Linux (arm64)
curl -LO https://github.com/SCGIS-Wales/helm-mcp/releases/latest/download/helm-mcp-linux-arm64
chmod +x helm-mcp-linux-arm64
sudo mv helm-mcp-linux-arm64 /usr/local/bin/helm-mcp

从源代码构建

需要 Go 1.27.2+。

git clone https://github.com/SCGIS-Wales/helm-mcp.git
cd helm-mcp
make build

Docker

docker build -t helm-mcp .
docker run -v ~/.kube:/home/helmuser/.kube:ro helm-mcp --mode stdio

Python 包

pip install helm-mcp

完整详情请参阅下文的 Python 包。

快速开始

stdio 模式（适用于 Claude Code、Cursor 等）

helm-mcp --mode stdio

HTTP 模式（Streamable HTTP）

helm-mcp --mode http

HTTP 模式默认监听 127.0.0.1:8080。如需接受远程客户端，请配置身份验证（参见身份验证）并显式绑定地址，例如 --addr 0.0.0.0:8080。

HTTP 模式默认无状态（MCP 2026-07-28）：没有 initialize 握手，也没有 Mcp-Session-Id 标头，因此服务可以部署在普通的轮询负载均衡器后，无需粘性会话或共享会话存储。使用较旧协议版本的客户端仍可正常工作——SDK 会自动协商到较低版本。

如果客户端需要旧版的按会话行为：

helm-mcp --mode http --stateless=false

已在 v0.2.0 中移除：--mode sse。 MCP 规范自 2025-03-26 起已弃用 HTTP+SSE 传输，并根据 2026-07-28 功能生命周期政策正式将其标记为弃用。请使用 --mode http，它会在同一地址提供 Streamable HTTP。

MCP 客户端配置

Claude Desktop

添加到 ~/.claude/claude_desktop_config.json：

{
  "mcpServers": {
    "helm": {
      "command": "helm-mcp",
      "args": ["--mode", "stdio"]
    }
  }
}

Claude Code

claude mcp add helm -- helm-mcp --mode stdio

Cursor / Windsurf / VS Code

添加到 MCP 服务配置中：

{
  "helm-mcp": {
    "command": "helm-mcp",
    "args": ["--mode", "stdio"]
  }
}

远程 / HTTP 客户端

以 HTTP 模式启动服务，然后将任意兼容 MCP 的客户端连接到该端点：

helm-mcp --mode http
# MCP endpoint: http://localhost:8080/mcp

MCP 协议支持

helm-mcp 实现了 MCP 2026-07-28，并会为较旧客户端自动协商到早期版本（2025-11-25、2025-06-18、2025-03-26、2024-11-05），因此升级服务无需升级客户端。

功能	状态
工具	支持：46 个工具，每个工具都有顶层 title、注释，以及（当结果具有稳定结构时）输出架构
进度	支持。helm_install、helm_upgrade、helm_uninstall、helm_rollback 和 helm_test 会在请求携带进度令牌时，每隔 10 秒发送一次 notifications/progress 心跳，因此在进度更新时重置超时的客户端会继续等待较长时间的 wait 操作
取消	支持。在 HTTP 模式下，断开的请求会取消正在运行的工具调用，就像 Ctrl+C 会取消 helm CLI 一样（使用 --propagate-cancellation=false 可让操作继续完成）
无状态传输	支持，且为 --mode http 的默认设置（使用 --stateless=false 可选择不启用）
server/discover	支持
确定性的 tools/list 顺序	支持——工具按名称排序返回，因此客户端和提示词缓存可以持续命中
服务说明	支持——服务会说明版本选择、集群定位和破坏性工具的安全性
资源 / 提示词	不适用——每项 Helm 操作都是一次工具调用
Tasks 扩展	未实现。它适用于较长时间运行的 helm install --wait 操作，但客户端支持仍然有限。已列为后续工作。
MRTR / 引导	未实现，这是有意为之。Helm 工具将所有输入都作为参数传入，因此调用过程中无需提问。
Roots / Sampling / Logging	未实现。根据 2026-07-28（SEP-2577），这三项均已弃用。
HTTP+SSE 传输	已在 v0.2.0 中移除——已被规范弃用。请使用 --mode http。

可用工具（46）

发布管理（14）

工具	描述
helm_install	将 Helm chart 安装为新版本
helm_upgrade	将版本升级到新的 chart 版本或配置值
helm_uninstall	卸载版本并移除相关资源
helm_rollback	将版本回滚到之前的修订版本
helm_list	列出版本（支持筛选、排序和分页）
helm_status	显示版本状态、修订版本、chart 和配置值
helm_history	显示版本的修订历史
helm_test	运行版本的测试套件
helm_get_all	获取版本的所有信息（配置值、清单、钩子、说明）
helm_get_hooks	获取版本的钩子
helm_get_manifest	获取版本的 Kubernetes 清单
helm_get_metadata	获取版本的元数据
helm_get_notes	获取版本的说明
helm_get_values	获取版本的配置值（用户提供或计算所得）

Chart 管理（14）

工具	描述
helm_create	创建新的 chart，也可基于 starter 创建
helm_lint	检查 chart 中的问题和最佳实践
helm_template	在本地渲染模板和钩子，无需安装
helm_package	将 chart 目录打包为归档文件（.tgz）
helm_pull	从仓库或 OCI registry 下载 chart
helm_push	将 chart 归档文件推送到 OCI registry
helm_verify	验证 chart 是否具有有效的来源证明文件
helm_show_all	显示 chart 的所有信息（Chart.yaml、配置值、README、CRD）
helm_show_chart	显示 chart 的 Chart.yaml
helm_show_crds	显示 chart 的 CRD
helm_show_readme	显示 chart 的 README
helm_show_values	显示 chart 的默认配置值
helm_dependency_build	根据 Chart.lock 构建 charts/ 目录
helm_dependency_list	列出 chart 的依赖项

仓库管理（5）

工具	描述
helm_repo_add	添加 chart 仓库
helm_repo_list	列出已配置的 chart 仓库
helm_repo_update	更新 chart 仓库索引
helm_repo_remove	移除 chart 仓库
helm_repo_index	为 chart 归档文件生成索引文件

Registry / OCI（2）

工具	描述
helm_registry_login	登录 OCI registry
helm_registry_logout	退出 OCI registry

搜索（2）

工具	描述
helm_search_hub	在 Artifact Hub 中搜索 chart
helm_search_repo	搜索本地配置的仓库

插件管理（6）

工具	描述
helm_plugin_install	安装 Helm 插件
helm_plugin_list	列出已安装的插件
helm_plugin_uninstall	卸载插件
helm_plugin_update	更新插件
helm_plugin_package	将插件目录打包为已签名的归档文件（仅限 v4）
helm_plugin_verify	验证已打包插件的签名和来源证明（仅限 v4）

环境（2）

工具	描述
helm_env	打印 Helm 环境信息
helm_version	打印 Helm SDK 版本信息

依赖项更新（1）

工具	描述
helm_dependency_update	根据 Chart.yaml 更新 charts/

工具注解

每个工具都带有 MCP 注解，让客户端——或正在决定调用哪个工具的 Agent——能够一眼区分读取集群状态的操作和更改集群状态的操作。

注解	含义	工具
readOnlyHint: true	只读取状态；可以放心调用	helm_list、helm_status、helm_history、所有 helm_get_*、所有 helm_show_*、helm_repo_list、helm_plugin_list、helm_dependency_list、helm_env、helm_version、helm_lint、helm_template、helm_verify、helm_plugin_verify、helm_search_*
destructiveHint: true	可能移除或替换线上状态——仅在用户明确要求时调用	helm_uninstall、helm_rollback、helm_upgrade、helm_repo_remove、helm_plugin_uninstall
openWorldHint: true	访问已配置集群之外的资源（Artifact Hub、OCI 注册表、Chart 仓库）	helm_search_hub、helm_search_repo、helm_pull、helm_push、所有 helm_show_*、helm_template、所有 helm_registry_*
idempotentHint: true	使用相同参数重复调用不会产生额外效果	所有只读工具，以及 helm_repo_add、helm_repo_update、所有 helm_dependency_*、helm_plugin_update

未列为破坏性的工具均标注为 destructiveHint: false；这一点很重要，因为 MCP 规范默认将该提示设为 true。

注解只是提示，并非安全边界——客户端可能会忽略它们。要建立真正的安全边界，请使用 Security 下所述的 OIDC 作用域和角色。

结构化输出

有 11 个工具会发布 outputSchema，并在返回可读文本的同时返回 structuredContent，以便客户端无需解析文本即可使用结果：

helm_list、helm_status、helm_history、helm_get_metadata、helm_get_values、helm_repo_list、helm_search_repo、helm_search_hub、helm_plugin_list、helm_env、helm_version。

// helm_list
{
  "releases": [
    { "name": "my-app", "namespace": "default", "revision": 3, "status": "deployed", ... }
  ],
  "count": 1
}

现有的 JSON 文本内容保持不变，因此解析这些内容的客户端仍可正常工作。集合会封装在带有 count 的对象中，而不是作为裸数组返回。输出为自由格式 YAML 或文本的工具——helm_template、helm_lint、helm_get_manifest、helm_show_*、helm_package、helm_dependency_list——没有输出架构，因为没有有用的结构可供声明。

Helm CLI 覆盖情况

helm CLI 命令与对应 helm-mcp MCP 工具的完整映射。

Helm 命令	MCP 工具	状态
helm create	helm_create	已覆盖
helm dependency build	helm_dependency_build	已覆盖
helm dependency list	helm_dependency_list	已覆盖
helm dependency update	helm_dependency_update	已覆盖
helm env	helm_env	已覆盖
helm get all	helm_get_all	已覆盖
helm get hooks	helm_get_hooks	已覆盖
helm get manifest	helm_get_manifest	已覆盖
helm get metadata	helm_get_metadata	已覆盖
helm get notes	helm_get_notes	已覆盖
helm get values	helm_get_values	已覆盖
helm history	helm_history	已覆盖
helm install	helm_install	已覆盖
helm lint	helm_lint	已覆盖
helm list	helm_list	已覆盖
helm package	helm_package	已覆盖
helm plugin install	helm_plugin_install	已覆盖
helm plugin list	helm_plugin_list	已覆盖
helm plugin uninstall	helm_plugin_uninstall	已覆盖
helm plugin package	helm_plugin_package	已覆盖（仅 v4）
helm plugin update	helm_plugin_update	已覆盖
helm plugin verify	helm_plugin_verify	已覆盖（仅 v4）
helm pull	helm_pull	已覆盖
helm push	helm_push	已覆盖
helm registry login	helm_registry_login	已覆盖
helm registry logout	helm_registry_logout	已覆盖
helm repo add	helm_repo_add	已覆盖
helm repo index	helm_repo_index	已覆盖
helm repo list	helm_repo_list	已覆盖
helm repo remove	helm_repo_remove	已覆盖
helm repo update	helm_repo_update	已覆盖
helm rollback	helm_rollback	已覆盖
helm search hub	helm_search_hub	已覆盖
helm search repo	helm_search_repo	已覆盖
helm show all	helm_show_all	已覆盖
helm show chart	helm_show_chart	已覆盖
helm show crds	helm_show_crds	已覆盖
helm show readme	helm_show_readme	已覆盖
helm show values	helm_show_values	已覆盖
helm status	helm_status	已覆盖
helm template	helm_template	已覆盖
helm test	helm_test	已覆盖
helm uninstall	helm_uninstall	已覆盖
helm upgrade	helm_upgrade	已覆盖
helm verify	helm_verify	已覆盖
helm version	helm_version	已覆盖
helm completion	—	不适用（Shell 工具）
helm help	—	不适用（Shell 工具）

46 个中的 46 个 Helm 操作命令均已覆盖。唯一排除的命令（completion、help）是 Shell 工具，在 MCP 上下文中没有意义。

helm plugin package 和 helm plugin verify 随 Helm v4 一同引入，支持带签名的插件分发，因此需要设置 helm_version: "v4"。

标志覆盖范围

命令会覆盖其标志，而不仅仅是名称。工具接受的每个参数都会传递给 Helm SDK，而会改变渲染或应用行为的参数则由测试覆盖，这些测试会渲染真实图表或对其进行试运行。以下标志有意不公开：

标志	原因
Helm v3 中的 --post-renderer	v3 后置渲染器会在服务端主机上执行任意二进制文件。Helm v4 后置渲染器是已安装的插件，并通过 post_renderer 公开
--set 和 --set-json	由内联 values 对象覆盖，它会像 --set 一样进行深度合并
template --output-dir	helm_template 为只读；请将 output_dir 与 helm_install 配合使用
create --chart-api-version v3	在 Helm 4.3 中属于实验性功能，且受功能门控限制
history --show-rollback-revision、get --template、version --template	仅用于展示；结构化结果已包含这些数据
search hub --endpoint、search --fail-on-no-result、repo index --json	对 Agent 价值较低；可按需添加
push --username/--password、plugin install TLS 和注册表身份验证	请先使用 helm_registry_login，它会存储凭据供后续调用使用

Kubernetes 身份验证

每个工具都可通过 GlobalInput 接受以下身份验证字段：

字段	JSON 键	描述
Kubeconfig	kubeconfig	kubeconfig 文件路径（默认为 $KUBECONFIG 或 ~/.kube/config）
上下文	kube_context	要使用的 Kubernetes 上下文名称
API 服务器	kube_apiserver	覆盖 kubeconfig 中的 API 服务器 URL
Bearer 令牌	kube_token	用于 API 身份验证的 Bearer 令牌
TLS 服务器名称	kube_tls_server_name	用于 TLS 证书验证的服务器名称
不安全 TLS	kube_insecure_tls	跳过 TLS 证书验证
命名空间	namespace	目标 Kubernetes 命名空间

EKS（AWS）

EKS 在 kubeconfig 中使用基于 exec 的身份验证。由 aws eks update-kubeconfig 生成的标准 kubeconfig 开箱即用：

{
  "kubeconfig": "/home/user/.kube/config",
  "kube_context": "arn:aws:eks:us-east-1:123456789:cluster/my-cluster"
}

也可以使用直接令牌身份验证：

{
  "kube_apiserver": "https://ABCDEF.gr7.us-east-1.eks.amazonaws.com",
  "kube_token": "<bearer-token-from-aws-eks-get-token>"
}

GKE（Google Cloud）

由 gcloud container clusters get-credentials 生成的 GKE kubeconfig 开箱即用：

{
  "kubeconfig": "/home/user/.kube/config",
  "kube_context": "gke_my-project_us-central1_my-cluster"
}

AKS（Azure）

由 az aks get-credentials 生成的 AKS kubeconfig 开箱即用：

{
  "kubeconfig": "/home/user/.kube/config",
  "kube_context": "my-aks-cluster"
}

Helm 版本选择

每个工具都支持 helm_version 字段，用于在 Helm v3 和 v4 之间进行选择：

{
  "helm_version": "v4",
  "release_name": "my-release"
}

• "v4"（默认）：Helm v4 SDK，支持服务端应用、基于插件的后置渲染器和已签名插件
• "v3"：Helm v3 SDK，用于向后兼容

仅限 v4 的功能

这些字段需要 helm_version: "v4"。如果与 "v3" 一起传入，会报错，而不会静默忽略。

字段	工具	说明
server_side_apply	install、upgrade、rollback	请参阅服务端应用。v3 接受 false，并始终在客户端应用
force_conflicts	install、upgrade、rollback	接管由其他字段管理器拥有的字段
wait_strategy	install、upgrade、rollback、uninstall	请参阅下文
post_renderer、post_renderer_args	install、upgrade、template	已安装的后置渲染器插件名称
description	rollback	记录在回滚修订版本上的描述
verify、keyring	plugin install	verify: false 可安装未签名的插件，例如 helm-diff

有两个工具完全仅适用于 v4：helm_plugin_package 和 helm_plugin_verify。

服务端应用

Helm 4 默认使用 Kubernetes 服务端应用（server side apply）。helm_install 也遵循这一行为：将 server_side_apply 留空即可使用服务端应用，或将其设为 false 以使用客户端应用（client side apply）。对于 helm_upgrade 和 helm_rollback，如果 未设置该值，Helm 会保持 auto 模式，即重用上一个版本记录的应用方法。版本结果会通过 apply_method（"ssa" 或 "csa"）报告该方法。

在 v0.5.0 之前，v4 引擎会在每次安装和回滚时强制使用客户端应用，除非 server_side_apply 为 true。如果你依赖客户端应用，请传入 server_side_apply: false。

等待：wait 和 wait_strategy

Helm v4 用策略枚举取代了 v3 的布尔型 --wait，因此 helm_install、helm_upgrade、helm_rollback 和 helm_uninstall 都接受一个 wait_strategy 字段，以及 wait：

wait_strategy	行为
"watcher"	使用 kstatus 等待，即 v4 中 helm --wait 的行为
"legacy"	使用 v3 的就绪状态检查等待
"hookOnly"	仅等待钩子；省略 --wait 时 CLI 的默认值

设置 wait_strategy 时，它的优先级更高。否则，wait: true 会映射为 "watcher"，wait: false 会映射为 "hookOnly"。

在 v0.2.0 之前，v4 引擎会将 watcher 策略硬编码，因此 wait: false 会被静默忽略，所有 v4 操作都会等待。如果你依赖这一行为，请显式设置 wait: true（或 wait_strategy: "watcher"）。

v3 和 v4 均支持

rollback_on_failure（Helm 的 --atomic）受两个引擎支持，可用于 helm_install 和 helm_upgrade。以下选项也受支持：devel、sub_notes、 hide_notes、skip_schema_validation、disable_openapi_validation、 enable_dns、take_ownership 和 hide_secret；helm_install 支持 output_dir、use_release_name 和 force_replace； helm_upgrade 支持 reset_then_reuse_values；helm_uninstall 支持 ignore_not_found 和 description；helm_list 支持 all、uninstalling、time_format 和 selector；helm_status 支持 show_resources；helm_test 支持 logs；helm_show_* 工具支持 jsonpath。

Chart 源

helm_install、helm_upgrade、helm_template、helm_pull 和 helm_show_* 工具接受 Helm 的 Chart 位置标志：repo、username、 password、ca_file、cert_file、key_file、insecure_skip_tls_verify、 plain_http、pass_credentials、verify 和 keyring。 TLS 和凭据选项也适用于 oci:// Chart。

verify 会使用 keyring 检查 Chart 来源证明。和 CLI 一样，keyring 默认为 $GNUPGHOME/pubring.gpg（或 ~/.gnupg）。对于 helm_pull，prov 会下载来源证明文件，但不进行验证（helm pull --prov）。

升级或安装

如果版本不存在，helm_upgrade 配合 install: true 会安装该版本；如果其上一个修订版已卸载，则会替换该版本，行为与 helm upgrade --install 完全相同。create_namespace 适用于该安装操作。

值

值会按照 Helm 使用的顺序合并：先是 values_files，然后是内联的 values 对象（深度合并，类似于 --set），接着是 set_string、set_file 和 set_literal，它们各自都是 key=value 字符串列表。set_file 只读取本地文件， 并会验证它将读取的每个路径，包括 {a,b} 列表中的路径以及后续以逗号分隔的键值对。

Chart 依赖项

helm_install、helm_upgrade 和 helm_template 中的 dependency_update 会像 CLI 标志一样，在渲染前获取缺失的依赖项。不设置该选项时，未附带依赖项的 Chart 会被报告为错误，而不会在缺少子 Chart 的情况下进行渲染。

Python 包

现已提供一个 Python 封装，它使用 FastMCP 围绕 helm-mcp Go 二进制文件创建透明代理。添加到 Go 二进制文件中的新工具会自动在 Python 中可用，无需修改代码。

安装

pip install helm-mcp

需要 Python 3.12+。Go 二进制文件已打包在特定平台的 wheel 中——无需安装 Go 工具链。支持的平台：linux-amd64、linux-arm64、darwin-amd64、darwin-arm64、windows-amd64。首次使用时会从 wheel 中提取二进制文件，并通过 SHA256 校验和验证来防止篡改。

你可以验证二进制文件是否可用：

helm-mcp-python --setup

作为服务使用

from helm_mcp import create_server

# stdio mode (default, for MCP clients)
server = create_server()
server.run()

# HTTP mode
server = create_server()
server.run(transport="http", host="127.0.0.1", port=8080)

作为客户端使用

import asyncio
from helm_mcp import create_client

async def main():
    async with create_client() as client:
        # List all available tools
        tools = await client.list_tools()
        print(f"Available tools: {len(tools)}")

        # List Helm releases
        result = await client.call_tool("helm_list", {"namespace": "default"})
        print(result)

        # Install a chart
        result = await client.call_tool("helm_install", {
            "release_name": "my-app",
            "chart": "bitnami/nginx",
            "namespace": "default",
        })
        print(result)

asyncio.run(main())

CLI

# stdio mode (for MCP clients like Claude Code)
helm-mcp-python

# HTTP mode (loopback only by default; the Python proxy has no authentication)
helm-mcp-python --transport http --port 8080

# Bind to all interfaces only behind your own authenticating proxy
helm-mcp-python --transport http --host 0.0.0.0 --allow-remote

# Custom binary path
helm-mcp-python --binary /usr/local/bin/helm-mcp

与 FastMCP 集成

该 Python 包基于 FastMCP 构建，并返回标准的 FastMCP 服务端／客户端对象。你可以将它与其他 FastMCP 服务组合使用：

from fastmcp import FastMCP
from helm_mcp import create_server as create_helm_server

# Create a composite server
app = FastMCP("my-platform")

# Mount helm-mcp as a sub-server
helm = create_helm_server()
app.mount("helm", helm)

# Add your own tools alongside Helm
@app.tool()
def my_custom_tool(param: str) -> str:
    return f"Custom: {param}"

app.run()

二进制文件查找

Python 包按以下顺序查找 helm-mcp Go 二进制文件：

1. HELM_MCP_BINARY 环境变量
2. 包中 bin/ 目录下打包的二进制文件
3. 从 GitHub Releases 自动下载（并验证 SHA256 校验和）
4. PATH 中的 helm-mcp

环境变量

代理会将以下环境变量转发给 Go 子进程：

类别	变量
代理	HTTP_PROXY、HTTPS_PROXY、NO_PROXY（以及小写形式）
Kubernetes	KUBECONFIG、KUBERNETES_SERVICE_HOST、KUBERNETES_SERVICE_PORT
Helm	HELM_CACHE_HOME、HELM_CONFIG_HOME、HELM_DATA_HOME、HELM_PLUGINS、HELM_DEBUG
AWS	AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY、AWS_SESSION_TOKEN、AWS_REGION、AWS_PROFILE
GCP	GOOGLE_APPLICATION_CREDENTIALS、CLOUDSDK_COMPUTE_ZONE
Azure	AZURE_TENANT_ID、AZURE_CLIENT_ID、AZURE_CLIENT_SECRET、AZURE_SUBSCRIPTION_ID
TLS	SSL_CERT_FILE、SSL_CERT_DIR

弹性配置（Python）

该 Python 包基于 FastMCP 中间件、circuitbreaker 和 tenacity 构建了全面的弹性机制。所有设置均可通过 HELM_MCP_* 环境变量配置，并提供合理的默认值。

环境变量

变量	类型	默认值	描述
HELM_MCP_RETRY_ENABLED	bool	true	启用代理层重试中间件
HELM_MCP_RETRY_MAX_RETRIES	int	2	最大重试次数
HELM_MCP_RETRY_BASE_DELAY	float	1.0	初始退避延迟（秒）
HELM_MCP_RETRY_MAX_DELAY	float	30.0	最大退避延迟（秒）
HELM_MCP_RETRY_BACKOFF_MULTIPLIER	float	2.0	退避乘数
HELM_MCP_RATE_LIMIT_ENABLED	bool	false	启用令牌桶速率限制
HELM_MCP_RATE_LIMIT_MAX_RPS	float	10.0	每秒最大请求数（必须大于 0）
HELM_MCP_RATE_LIMIT_BURST	int	20	突发容量（至少为 1；无效值会导致启动失败）
HELM_MCP_CACHE_ENABLED	bool	false	启用基于 TTL 的响应缓存
HELM_MCP_CACHE_TOOL_TTL	int	300	工具调用缓存 TTL（秒）
HELM_MCP_CACHE_LIST_TTL	int	60	工具列表缓存 TTL（秒）
HELM_MCP_ERROR_HANDLING_ENABLED	bool	true	启用结构化错误响应
HELM_MCP_ERROR_INCLUDE_TRACEBACK	bool	false	在错误中包含回溯信息
HELM_MCP_TIMING_ENABLED	bool	true	启用请求计时
HELM_MCP_TIMING_DETAILED	bool	false	使用详细计时中间件
HELM_MCP_CIRCUIT_BREAKER_ENABLED	bool	true	在工具调用中启用断路器
HELM_MCP_CIRCUIT_BREAKER_FAILURE_THRESHOLD	int	5	断路器打开前的失败次数
HELM_MCP_CIRCUIT_BREAKER_RESET_TIMEOUT	float	30.0	半开状态重试前的等待秒数
HELM_MCP_TENACITY_ENABLED	bool	true	启用带抖动的 tenacity 重试
HELM_MCP_TENACITY_MAX_ATTEMPTS	int	3	最大重试次数
HELM_MCP_TENACITY_MIN_WAIT	float	0.5	重试间的最短等待时间（秒）
HELM_MCP_TENACITY_MAX_WAIT	float	10.0	重试间的最长等待时间（秒）
HELM_MCP_TENACITY_MULTIPLIER	float	1.5	指数退避基数
HELM_MCP_BULKHEAD_ENABLED	bool	true	启用并发限制器
HELM_MCP_BULKHEAD_MAX_CONCURRENT	int	10	最大并发工具调用数
HELM_MCP_OTEL_ENABLED	bool	false	启用 OpenTelemetry 跟踪
HELM_MCP_OTEL_SERVICE_NAME	str	helm-mcp	OTel 服务名称
HELM_MCP_OTEL_EXPORTER	str	console	OTel 导出器（console 或 otlp）

CLI 标志

helm-mcp-python --no-retry                   # Disable proxy retry middleware
helm-mcp-python --rate-limit 50              # Enable rate limiting at 50 rps
helm-mcp-python --cache                      # Enable response caching
helm-mcp-python --no-circuit-breaker         # Disable circuit breaker
helm-mcp-python --bulkhead-max 5             # Limit to 5 concurrent tool calls
helm-mcp-python --otel                       # Enable OpenTelemetry tracing

以编程方式配置

from helm_mcp import create_server, HelmClient
from helm_mcp.resilience import (
    ResilienceConfig,
    RateLimitConfig,
    CircuitBreakerConfig,
    BulkheadConfig,
)

# Server with custom resilience
config = ResilienceConfig(
    rate_limit=RateLimitConfig(enabled=True, max_requests_per_second=50),
    circuit_breaker=CircuitBreakerConfig(failure_threshold=3),
    bulkhead=BulkheadConfig(max_concurrent=20),
)
server = create_server(resilience=config)

# Client with custom resilience
async with HelmClient(resilience=config) as helm:
    releases = await helm.list(namespace="default")

OpenTelemetry

FastMCP 通过 OpenTelemetry API 发出跟踪数据。要接收实际的跟踪数据，请安装 SDK：

pip install helm-mcp[otel]

然后启用跟踪：

export HELM_MCP_OTEL_ENABLED=true
export HELM_MCP_OTEL_EXPORTER=otlp        # or "console"
export HELM_MCP_OTEL_SERVICE_NAME=helm-mcp

响应负载管理

大型 Helm 输出（清单、值、模板渲染结果）可能会超出大模型的上下文窗口。helm-mcp 包含两层响应大小管理机制，以防止这种情况。

响应截断

所有工具响应在超出可配置的大小限制时都会自动截断。默认值为 256 KB（约 64K 个词元）。截断的响应会包含元数据，指出原始大小，并建议使用更具体的查询。

通过 CLI 标志或环境变量配置限制：

# CLI flag (in bytes, 0 to disable)
helm-mcp --mode stdio --max-response-bytes 524288

# Environment variable
export HELM_MCP_MAX_RESPONSE_BYTES=524288
helm-mcp --mode stdio

CLI 标志的优先级高于环境变量。

清理清单

返回 Kubernetes YAML 的工具（helm_get_manifest、helm_get_all、helm_get_hooks、helm_template）会在返回结果前自动剔除冗余字段。这样通常可以将清单大小减少 40-60%，而不会丢失有意义的信息。

剔除的字段：

• metadata.managedFields — Kubernetes 内部管理记录（通常是最大的单个字段）
• kubectl.kubernetes.io/last-applied-configuration — 整个对象的冗余副本
• deployment.kubernetes.io/revision — 控制器内部注解
• control-plane.alpha.kubernetes.io/leader — 领导者选举数据

此清理始终启用且无法禁用，因为这些字段对大模型交互毫无用处。原始的、未经清理的数据仍可通过直接访问 kubectl 获取。

弹性机制

internal/resilience 包提供了额外的生产环境弹性模式：

模式	说明
熔断器	三态（Closed/Open/HalfOpen）模式；当后端不可用时快速失败。可配置失败阈值和恢复超时时间。
带退避的重试	对暂时性故障采用带抖动的指数退避。支持感知上下文的取消和可重试错误筛选。
按工具设置超时	按类别设定默认超时时间：query（30s）、mutate（120s）、chart（60s）、repo（60s）。遵循现有的上下文截止时间。

已知限制

插件工具使用 Helm CLI

所有六个插件工具都会调用系统的 helm CLI；这是 helm-mcp 中唯一不使用 Helm Go SDK 的部分，因为 Helm 的插件包属于内部包，无法导入。

• Helm v4 默认会验证插件签名。未签名的插件（例如 helm-diff）可通过 helm_plugin_install 和 verify: false 安装。
• 已发布的容器镜像内置了固定版本的 helm CLI，因此其中的插件工具可以正常工作。如果直接运行二进制文件，helm 必须位于 PATH 中；并且在默认 helm_version: "v4" 设置下，它必须是 Helm v4 CLI：v3 CLI 会拒绝 --verify=false 等 v4 标志。

安全性

进程加固（Linux）

在 Linux 上运行时，helm-mcp 会在启动时应用进程级加固措施，以缩小 stdio 传输的攻击面。作为 IDE 子进程运行的 MCP 服务会继承用户的全部权限——这些缓解措施会限制进程遭到入侵时攻击者能造成的影响。

机制	功能
PR_SET_DUMPABLE(0)	阻止 ptrace 附加、生成核心转储和读取 /proc/pid/mem。防止其他进程检查内存中的凭据。
删除能力	从边界集中删除所有 Linux 能力。对非 root 用户（常见情况）不执行任何操作，但在配置不当的 Docker/Kubernetes 环境中运行时，可防止权限提升。
凭据内存清零	每个工具处理程序完成后，都会通过 defer 调用 ZeroCredentials()，覆盖内存中的 bearer token 和密码。这是纵深防御措施——Go 字符串不可变，垃圾回收器也可能保留副本，但此举可缩短凭据在代码路径中的存留时间。

加固措施采用尽力而为且不致命的方式——发生故障时会记录日志（需使用 --debug），但绝不会导致进程崩溃。在非 Linux 平台（macOS、Windows）上，会跳过加固并记录一条提示信息。

# Verify hardening is active (Linux)
helm-mcp --mode stdio --debug 2>&1 | grep "security hardening"

# Disable for debugging (e.g., when using strace or delve)
helm-mcp --mode stdio --no-harden

已评估但未实施的机制

机制	跳过原因
Seccomp BPF	服务使用 exec.CommandContext 执行插件，并通过网络与 Kubernetes API 和注册表通信。系统调用范围过广，若要安全地进行筛选，就可能破坏不同内核版本上的 Helm SDK 内部功能。
命名空间隔离	进程需要访问 ~/.kube/config、云凭据文件、DNS 和网络。命名空间隔离会破坏核心功能。
Cgroup 资源限制	5 分钟的 pluginExecTimeout 已能限制失控操作，而 IDE 会管理进程生命周期。
AppArmor/SELinux 配置文件	动态文件路径会带来高昂的维护成本。将其作为外部构件部署，比嵌入二进制文件更合适。

凭据清理

系统会自动清理所有错误消息，移除以下内容：

• Bearer 令牌（包括 EKS、GKE 和 Azure JWT 令牌）
• Basic 身份验证凭据
• URL 中嵌入的密码（https://user:password@host）

输入验证

每个工具处理程序都会在执行前调用 ValidateGlobalInput，确保对每个请求中的命名空间和 kubeconfig 字段进行验证。

安全软件包提供以下验证器：

• Release 名称（符合 DNS-1123 规范）
• 命名空间名称
• Kubeconfig 文件路径（防止路径遍历、检测符号链接、拒绝敏感路径 — 禁止访问 /etc/shadow、/proc/、/dev/、/sys/）
• URL（方案验证 + SSRF 防护：通过 DNS 解析并屏蔽私有 IP，包括 0.0.0.0/8、127.0.0.0/8、10.0.0.0/8、100.64.0.0/10、172.16.0.0/12、192.168.0.0/16、169.254.0.0/16、IPv4 映射地址、NAT64，以及 IPv6 未指定地址、环回、本地链路和唯一本地地址范围）。适用于仓库 URL、URL 图表引用、远程 values 文件和 OCI 推送目标
• 文件路径（防止路径遍历、拒绝符号链接，包括符号链接的父目录，并拒绝敏感路径）。适用于 values 文件、set_file 条目、密钥环、CA/证书/密钥文件、密码短语文件、输出和解包目录、helm_lint 与 helm_package 的图表路径，以及 helm_create 的图表名称和 starter
• 仓库名称（字母数字字符、点、短横线和下划线；防止缓存路径遍历）
• 超时期限（最长 24 小时）
• 插件名称（字母数字字符、短横线和下划线；不得以短横线开头，以防止参数注入）

文件权限

• 仓库配置文件以 0600 权限写入（仅所有者可读写）
• 配置目录以 0700 权限创建（仅所有者可访问）

HTTP 服务强化

以 HTTP 模式运行时：

• 除非通过 --addr 指定其他地址，否则监听 127.0.0.1:8080
• ReadHeaderTimeout: 10s 和 ReadTimeout: 30s — 防止客户端慢速攻击
• WriteTimeout: 30m（--write-timeout）— 足以应对带有 wait 的 helm_install/helm_upgrade；如果客户端使用更长的 Helm 超时时间，请调高此值
• 请求断开时会取消其工具调用（默认启用 --propagate-cancellation），因此已放弃的操作不会一直运行到写入超时
• IdleTimeout: 120s — 回收空闲连接
• MaxHeaderBytes: 1MB — 防止基于标头的 DoS 攻击
• 以 5 秒超时进行优雅关停

身份验证（OIDC/OAuth2）

以 HTTP 模式运行时，helm-mcp 支持 OAuth2/OIDC 身份验证，包括 JWT 验证、基于声明的授权和结构化审计日志。这符合 MCP 安全最佳实践。

身份验证完全由用户选择启用。 未设置 OIDC 或令牌环境变量时，服务将不启用身份验证（与先前版本相同）。Stdio 模式不受身份验证配置影响。

快速入门 — Entra ID（Azure AD / ADFS）

# Required: issuer and audience
export HELM_MCP_OIDC_ISSUER="https://login.microsoftonline.com/{tenant-id}/v2.0"
export HELM_MCP_OIDC_AUDIENCE="api://helm-mcp-server"

# Optional: restrict access by scopes, roles, or client app IDs
export HELM_MCP_REQUIRED_SCOPES="helm.read,helm.write"
export HELM_MCP_REQUIRED_ROLES="HelmOperator"
export HELM_MCP_ALLOWED_CLIENTS="client-app-id-1,client-app-id-2"

# Optional: explicit JWKS URL (auto-discovered from issuer if omitted)
export HELM_MCP_OIDC_JWKS_URL="https://login.microsoftonline.com/{tenant-id}/discovery/v2.0/keys"

helm-mcp --mode http --addr 0.0.0.0:8080

身份验证事件（auth_success、auth_failure）会以 JSON 格式写入 stderr，日志级别为 Info，且不受 --debug 影响。

环境变量

变量	必需	描述
HELM_MCP_OIDC_ISSUER	是（用于 OIDC）	OIDC 颁发者 URL。令牌的 iss 声明必须匹配。
HELM_MCP_OIDC_AUDIENCE	是（用于 OIDC）	预期的 aud 声明。拒绝为其他资源颁发的令牌。
HELM_MCP_OIDC_JWKS_URL	否	用于签名验证的 JWKS 端点。若省略，则根据颁发者自动发现。
HELM_MCP_REQUIRED_SCOPES	否	scp 声明中必需的 OAuth2 作用域，以逗号分隔。
HELM_MCP_REQUIRED_ROLES	否	roles 声明中必需的应用角色，以逗号分隔。
HELM_MCP_ALLOWED_CLIENTS	否	azp/appid 声明中允许的客户端应用 ID，以逗号分隔。
HELM_MCP_SESSION_TTL	否	会话缓存的不活动 TTL（Go 时长，例如 5m、15m）。默认值：5m。
HELM_MCP_AUTH_TOKEN	否	静态 bearer 令牌（旧版）。优先级低于 OIDC。

身份验证优先级

1. OIDC/OAuth2 — 如果设置了 HELM_MCP_OIDC_ISSUER，则启用基于 JWKS 的 JWT 验证。
2. 静态 bearer 令牌 — 如果只设置了 HELM_MCP_AUTH_TOKEN，则使用常量时间比较。
3. 无身份验证 — 如果两者均未设置，服务将接受所有请求（适用于本地 stdio 使用场景）。

令牌验证

每个传入的 JWT 都会进行以下验证：

检查项	描述
签名	根据 JWKS 公钥验证 RSA 签名（RS256/384/512）。密钥会缓存 1 小时；遇到 kid 未命中时自动刷新（密钥轮换）。
颁发者（iss）	必须与 HELM_MCP_OIDC_ISSUER 完全匹配。
受众（aud）	必须与 HELM_MCP_OIDC_AUDIENCE 匹配。拒绝为其他 API 颁发的令牌——这是防止令牌透传的核心防护措施。
过期时间（exp）	必须存在。拒绝已过期的令牌。
授权方（azp/appid）	如果已配置，则与 HELM_MCP_ALLOWED_CLIENTS 进行核对。同时支持 OIDC azp 和 Entra ID v1 appid 声明。
作用域（scp）	将以空格分隔的作用域与 HELM_MCP_REQUIRED_SCOPES 进行核对。
角色（roles）	将应用角色数组与 HELM_MCP_REQUIRED_ROLES 进行核对。

会话缓存

验证通过的令牌会缓存在内存中，以避免重复查找 JWKS：

• 不活动 TTL：默认为 5 分钟（可通过 HELM_MCP_SESSION_TTL 配置，例如 5m、10m、1h）
• 令牌过期时间：缓存的令牌绝不会在其 exp 声明指定的时间之后使用
• 缓存键：原始 bearer 令牌的 SHA-256 哈希（避免在内存中存储原始令牌）
• 滑动窗口：每次访问都会重置不活动计时器
• 最大条目数：10,000（超出时淘汰最早的条目）

审计日志

启用 OIDC 身份验证后，每次身份验证尝试都会通过 slog 发出结构化审计事件：

level=INFO msg=security_audit audit.event_type=auth_success audit.principal_id=oid-123 [email protected] audit.tenant_id=tenant-abc audit.client_app_id=client-1 audit.scopes="helm.read helm.write" audit.token_id=uti-xyz audit.remote_addr=10.0.0.1:54321

审计事件包括：主体 ID/名称、租户 ID、客户端应用 ID、作用域、角色、令牌 ID、会话 ID、操作、资源、结果、持续时间和远程地址。启用 --debug 可查看完整审计信息，或配置日志聚合器以捕获 security_audit 消息。

代表用户（OBO）令牌交换

当 helm-mcp 需要代表已通过身份验证的用户调用下游 API（例如 Kubernetes API）时，它会将传入的令牌交换为一个作用域限定于该下游服务的新令牌。这样可以避免转发原始令牌，防止下游服务遭到入侵时令牌被滥用，或令牌的受众不匹配。

工作原理

User        MCP Client        helm-mcp (MCP Server)      Kubernetes API
 │              │                      │                        │
 ├─(SSO)──────▶│ gets token            │                        │
 │              │ aud=helm-mcp          │                        │
 │              ├─(Bearer token)──────▶│                        │
 │              │                      ├─OBO exchange──────────▶│
 │              │                      │ grant_type=jwt-bearer   │
 │              │                      │ assertion=user token    │
 │              │                      │ scope=K8s API scopes    │
 │              │                      │◀─new token──────────────│
 │              │                      │  aud=Kubernetes API     │
 │              │                      ├─(K8s API call)────────▶│
 │              │                      │  with OBO token         │

链中的每一跳都会：

1. 验证传入令牌的受众（必须与此服务匹配）
2. 通过 OBO 将其交换为面向下一个服务的新令牌
3. 在新令牌的声明中保留原始用户的身份
4. 触发新一轮条件访问评估（如果已在 Entra ID 中配置）

OBO 配置

# OBO token exchange (for downstream API calls with user context)
export HELM_MCP_OBO_TOKEN_URL="https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token"
export HELM_MCP_OBO_CLIENT_ID="helm-mcp-app-id"
export HELM_MCP_OBO_CLIENT_SECRET="helm-mcp-client-secret"

为什么不转发令牌？

将用户的令牌转发给下游服务很诱人，但也存在问题。MCP Security Best Practices 明确不建议这样做。使用 OBO 时，每个服务都会获得一个为其自身受众签发的令牌，且仅具有所需权限。如果令牌被截获，影响范围仅限于单个服务，而不是整个链路。

AWS EKS 和 OBO 支持

支持 OIDC 的 AWS EKS 1.34+

AWS EKS 从 EKS 1.21 开始支持使用 OIDC 身份提供商进行集群身份验证，并在 1.34+ 中进行了重大改进。不过，EKS 原生不支持将 Entra ID OBO 流用于 Kubernetes API 身份验证。身份验证模式各不相同：

模式	支持情况	详情
EKS OIDC 身份提供商	是	在 EKS 中将 Entra ID 配置为 OIDC 提供商。用户使用 Entra ID 令牌直接进行身份验证，其中 aud = EKS 集群。无需 OBO——令牌直接为集群签发。
IRSA（IAM 服务账户角色）	是	通过投影的服务账户令牌提供 Pod 级身份。这属于 M2M（客户端凭据），而非用户委派。
EKS Pod Identity	是（EKS 1.34+）	使用 EKS Pod Identity Agent 简化 Pod 身份验证。同样属于 M2M，而非用户委派。
OBO → Kubernetes API	部分支持	Entra ID OBO 可以为任何已注册资源签发令牌。如果 EKS 配置了 Entra ID 作为 OIDC 提供商，且 Kubernetes API 已在 Entra ID 中注册为应用，则 OBO 签发的令牌可以用于 EKS 身份验证。这需要在 EKS OIDC 提供商上自定义配置 --oidc-issuer-url、--oidc-client-id 和 --oidc-username-claim。

EKS 推荐模式：将 Entra ID 配置为 EKS OIDC 身份提供商。MCP 客户端对用户进行身份验证，并获取 aud = helm-mcp 的令牌。helm-mcp 验证此令牌，然后执行 OBO 交换，获取一个 aud = EKS 集群 OIDC 客户端 ID 的新令牌。此 OBO 签发的令牌用于 Kubernetes API 调用，从而保留用户身份并启用按用户进行的 RBAC。

AWS Labs MCP 和 OBO

AWS Labs MCP 服务（例如，awslabs/mcp）和 Amazon Bedrock AgentCore 均未实现 OAuth2 OBO 或 RFC 8693 Token Exchange。AgentCore 使用不同的模式：

• 用户身份传播：通过不透明的 X-Amzn-Bedrock-AgentCore-Runtime-User-Id HTTP 标头实现——不是经加密签名的令牌
• 出站身份验证：使用 OAuth Authorization Code（3Lo）或 Client Credentials（2Lo），但这些是独立的身份验证事件，不是委派身份传播
• Token Vault：存储第三方服务的刷新令牌，但作用范围是 Agent，而非用户委派

这意味着 AWS Labs MCP 服务无法原生参与 Entra ID OBO 链。如果你的架构需要通过 AWS 托管的 MCP 服务传播用户委派身份，则必须将 OBO 交换实现为自定义中间件层，或将 helm-mcp 内置的 OBO 支持用作参考实现。

转发代理支持

helm-mcp 遵循标准代理环境变量：

export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1,.internal.company.com

开发

前置条件

• Go 1.27.2+
• Python 3.12+（用于 Python 包）
• golangci-lint v2（可选，用于代码检查）

构建

make build        # Build binary
make install      # Install to $GOPATH/bin
make build-all    # Cross-compile for Linux/macOS (amd64/arm64)

测试

# Go tests
make test         # Run all tests with race detection and coverage
make test-short   # Run tests without integration tests

# Python tests
cd python && pip install -e ".[dev]" && pytest -v tests/

代码检查

make lint         # Run golangci-lint + go vet
make vet          # Run go vet only

安全检查

make security     # Run govulncheck

覆盖率

make coverage     # Generate coverage report (coverage.html)

架构

cmd/helm-mcp/          Entry point, transport selection, CLI flags
internal/
  helmengine/           Engine interface and shared types
    v3/                 Helm v3 SDK implementation
    v4/                 Helm v4 SDK implementation
  tools/                MCP tool handlers
    release/            Install, upgrade, uninstall, rollback, list, status, etc.
    chart/              Create, lint, template, package, pull, push, show, etc.
    repo/               Add, list, update, remove, index
    registry/           Login, logout
    search/             Hub, repo
    plugin/             Install, list, uninstall, update, package, verify
    env/                Env, version
  security/             Process hardening, input validation, credential scrubbing
  resilience/           Response budget, circuit breaker, retry, timeouts, manifest sanitisation
  server/               MCP server creation and tool registration
python/                 FastMCP-based Python wrapper
  src/helm_mcp/         Python package source
  tests/                Python tests

贡献

欢迎社区贡献！无论是错误报告、功能请求、文档改进还是代码贡献，我们都非常感谢。

请参阅 CONTRIBUTING.md，了解以下事项的详细指南：

• 设置开发环境
• 运行测试和代码检查工具
• 提交拉取请求
• 提交消息约定

社区

• 错误报告与功能请求：GitHub Issues
• 讨论与问题：GitHub Discussions
• 发布版本：GitHub Releases（每次合并到 main 时自动发布）

许可证

本项目采用 MIT License 许可，可免费使用、修改和分发。