helm MCP

MCP运维云端

提供方 SCGIS-Wales

运维云端 stdio · 本地进程 OAuth 授权 社区 / 第三方 ClaudeCursorVS Code
查看接入方式

一个开源的MCP协议服务器,为AI助手提供完整的Helm访问能力,支持通过自然语言管理Kubernetes部署。

一句话选型结论

按资料字段整理

helm MCP 属于运维云端类 MCP 服务器,stdio · 本地进程,OAuth 授权,可直接接入 Claude、Cursor、VS Code,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类运维云端 传输方式stdio · 本地进程 鉴权OAuth 授权 部署方式本地部署
GitHub 星标 1 仓库热度,无公开仓库时显示未标注
工具数 44 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

运维云端
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量44暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

支持客户端

适用场景

KubernetesGo本地部署HelmAI助手自然语言处理云原生

安装与配置

stdio · 本地进程 OAuth 授权
客户端在本机拉起子进程,数据不出本机
docker run -v ~/.kube:/home/helmuser/.kube:ro helm-mcp --mode stdio

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Docker,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后客户端会列出约 44 个工具,随便调一个只读工具确认能返回结果。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
云资源查询

查实例、存储、账单等云上资源状态。

部署与发布

把部署、重启、回滚这类操作接进对话。

监控与告警

拉取监控指标,异常时让模型帮你判断。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 资料标注 44 个工具,覆盖面较广,能满足多种调用。
  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。
  • 已适配 Claude、Cursor、VS Code,换客户端不用重新研究配置。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 使用前要准备好OAuth 授权对应的凭据,并按最小权限配置。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在运维云端场景里让模型直接调用外部能力的人。
  • 已经在用 Claude、Cursor 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
helm MCP当前 44 stdio · 本地进程 本地部署 有 2026-05-17
lobehub 未标注 stdio · 本地进程 本地部署 有 2026-04-11
TrendRadar 未标注 stdio · 本地进程 本地部署 有 2026-04-13
Ui Tars Desktop 8a825770 未标注 stdio · 本地进程 本地部署 有 2026-05-17
ruflo 未标注 stdio · 本地进程 本地部署 有 2026-04-13
FastGPT 未标注 stdio · 本地进程 本地部署 有 2026-04-11

服务器档案

运维云端
字段来自项目仓库与公开索引,中文说明由本站标注
提供方SCGIS-Wales上游标注的维护方 SCGIS-Wales
分类运维云端本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式OAuth 授权远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · Docker本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验2026-05-17上游最后核验时间

详细介绍

35.1 KB
来自项目仓库与上游目录的原文,未做删改

An open-source MCP (Model Context Protocol) server that gives AI assistants full access to Helm — the Kubernetes package manager. Built with the native Helm Go SDK, supporting both Helm 3.x and 4.x in a single binary.

Use natural language to manage your Kubernetes deployments.

Connect helm-mcp to Claude, Cursor, VS Code, or any MCP-compatible client to install charts, manage releases, search repositories, and more — all through conversation.


目录

  • 为什么要掌舵mcp?
  • 安装
  • 快速开始
  • MCP客户端配置
  • 可用工具
  • Helm CLI覆盖率
  • Kubernetes身份验证
  • Helm版本选择
  • Python包
  • 弹性配置(Python)
  • 响应有效载荷管理
  • 已知限制
  • 安全
  • 身份验证(OIDC/OAuth2)
  • 代表(OBO)代币交易所
  • 发展
  • 建筑
  • 贡献
  • 社区
  • 许可证

为什么要掌舵mcp?

  • 44个MCP工具 涵盖每个Helm CLI命令(减去shell补全和帮助)
  • 双Helm SDK支持 --Helm v3和v4通过本机Go SDK(不是CLI包装器)
  • 三种运输方式 --stdio(默认)、HTTP(流式HTTP)、SSE
  • 云提供商就绪 --EKS、GKE、AKS kubeconfig格式开箱即用
  • 安全第一 --Linux进程强化、凭证内存清零、输入验证、路径遍历预防
  • Python 封装器 — FastMCP-基于代理的自动发现所有工具
  • 转发代理支持 --尊重 HTTP_PROXY, HTTPS_PROXY, NO_PROXY

安装

预构建二进制文件

从以下网址下载适用于您平台的最新版本 GitHub 发布:```bash

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.25+。```bash
git clone https://github.com/SCGIS-Wales/helm-mcp.git
cd helm-mcp
make build

码头工人```bash

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


### Python包```bash
pip install helm-mcp

看 Python包 下面是完整的细节。

快速开始

stdio模式(用于克劳德代码、光标等)```bash

helm-mcp --mode stdio


### HTTP模式(流式HTTP)```bash
helm-mcp --mode http --addr :8080

SSE模式(服务器发送事件)```bash

helm-mcp --mode sse --addr :8080


## MCP客户端配置

### 克劳德桌面版

添加 `~/.claude/claude_desktop_config.json`:```json
{
"mcpServers": {
"helm": {
"command": "helm-mcp",
"args": ["--mode", "stdio"]
}
}
}

克劳德代码```bash

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


### 光标/风帆/VS代码

添加到MCP服务器配置中:```json
{
"helm-mcp": {
"command": "helm-mcp",
"args": ["--mode", "stdio"]
}
}

远程/HTTP客户端

以HTTP模式启动服务器,然后将任何兼容MCP的客户端连接到端点:```bash
helm-mcp --mode http --addr :8080

MCP endpoint: http://localhost:8080/mcp


## 可用工具(44)

### 发布管理(14)

|工具|说明|
|------|-------------|
| `helm_install` |将Helm chart作为新版本安装|
| `helm_upgrade` |将版本升级到新的图表版本或值|
| `helm_uninstall` |卸载版本并删除相关资源|
| `helm_rollback` |将版本回滚到以前的版本|
| `helm_list` |列表发布(支持过滤器、排序、分页)|
| `helm_status` |显示发布状态、修订、图表和值|
| `helm_history` |显示版本的修订历史记录|
| `helm_test` |运行测试套件进行发布|
| `helm_get_all` |获取发布的所有信息(值、清单、钩子、注释)|
| `helm_get_hooks` |取下钩子释放|
| `helm_get_manifest` |获取Kubernetes清单以进行发布|
| `helm_get_metadata` |获取发布的元数据|
| `helm_get_notes` |获取发布笔记|
| `helm_get_values` |获取发布的值(用户提供或计算)|

### 图表管理(14)

|工具|说明|
|------|-------------|
| `helm_create` |使用给定名称创建新图表|
| `helm_lint` |为问题和最佳实践绘制图表|
| `helm_template` |在本地渲染模板,无需安装|
| `helm_package` |将图表目录打包到存档(.tgz)中|
| `helm_pull` |从存储库或OCI注册表下载图表|
| `helm_push` |将图表存档推送到OCI注册表|
| `helm_verify` |验证图表是否具有有效的来源文件|
| `helm_show_all` |显示所有图表信息(chart.yaml、值、README、CRD)|
| `helm_show_chart` |显示图表的Chart.yaml|
| `helm_show_crds` |显示图表的CRD|
| `helm_show_readme` |显示图表的自述文件|
| `helm_show_values` |显示图表的默认值|
| `helm_dependency_build` |从Chart.lock构建图表/目录|
| `helm_dependency_list` |列出图表的依赖关系|

### 存储库管理(5)

|工具|说明|
|------|-------------|
| `helm_repo_add` |添加图表存储库|
| `helm_repo_list` |列出已配置的图表存储库|
| `helm_repo_update` |更新图表存储库索引|
| `helm_repo_remove` |删除图表存储库|
| `helm_repo_index` |为图表存档生成索引文件|

### 注册处/保监处(2)

|工具|说明|
|------|-------------|
| `helm_registry_login` |登录OCI注册表|
| `helm_registry_logout` |从OCI注册表注销|

### 搜索(2)

|工具|说明|
|------|-------------|
| `helm_search_hub` |在Artifact Hub中搜索图表|
| `helm_search_repo` |搜索本地配置的存储库|

### 插件管理(4)

|工具|说明|
|------|-------------|
| `helm_plugin_install` |安装Helm插件|
| `helm_plugin_list` |列出已安装的插件|
| `helm_plugin_uninstall` |卸载插件|
| `helm_plugin_update` |更新插件|

### 环境(2)

|工具|说明|
|------|-------------|
| `helm_env` |打印Helm环境信息|
| `helm_version` |打印Helm SDK版本信息|

### 依赖关系更新(1)

|工具|说明|
|------|-------------|
| `helm_dependency_update` |更新图表/基于Chart.yaml|

## 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 update` | `helm_plugin_update` |覆盖|
| `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实用程序)|

**第44页,共44页** 涵盖了操作Helm命令。唯一被排除的命令(`completion`, `help`)是在MCP上下文中没有意义的shell实用程序。

## Kubernetes身份验证

每个工具都通过以下方式接受这些身份验证字段 `GlobalInput`:

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

### EKS(AWS)

EKS在kubeconfig中使用基于exec的身份验证。标准kubeconfig由生成 `aws eks update-kubeconfig` 开箱即用:```json
{
"kubeconfig": "/home/user/.kube/config",
"kube_context": "arn:aws:eks:us-east-1:123456789:cluster/my-cluster"
}

或者使用直接令牌身份验证:```json
{
"kube_apiserver": "https://ABCDEF.gr7.us-east-1.eks.amazonaws.com",
"kube_token": ""
}


### GKE(谷歌云)

GKE kubeconfig由生成 `gcloud container clusters get-credentials` 开箱即用:```json
{
"kubeconfig": "/home/user/.kube/config",
"kube_context": "gke_my-project_us-central1_my-cluster"
}

AKS(Azure)

KS kubeconfig由生成 az aks get-credentials 开箱即用:```json
{
"kubeconfig": "/home/user/.kube/config",
"kube_context": "my-aks-cluster"
}


## Helm版本选择

每个工具都支持 `helm_version` 在Helm v3和v4之间进行选择的字段:```json
{
"helm_version": "v4",
"release_name": "my-release"
}
  • "v4" (默认)--使用带有服务器端应用、WASM插件和标签选择器的Helm v4 SDK
  • "v3" --使用Helm v3 SDK实现向后兼容性

仅v4功能

这些字段仅在使用时可用 helm_version: "v4":

  • server_side_apply --使用Kubernetes服务器端应用程序
  • take_ownership --跳过Helm注释检查
  • rollback_on_failure --安装失败时自动回滚
  • hide_secret --隐藏模拟输出中的秘密
  • force_conflicts --武力冲突解决
  • selector --用于列表操作的标签选择器
  • show_resources --以状态显示资源表
  • reset_then_reuse_values --重置然后在升级中重用值

Python包

Python包装器可以使用 FastMCP 在helm-mcp-Go二进制文件周围创建一个透明的代理。添加到Go二进制文件中的新工具在Python中自动可用,无需更改代码。

安装```bash

pip install helm-mcp


需要Python 3.10+。Go二进制是 **捆绑在平台专用车轮内** --不需要Go工具链。支持的平台: `linux-amd64`, `linux-arm64`, `darwin-amd64`, `darwin-arm64`, `windows-amd64`。首次使用时从车轮中提取二进制文件,并进行SHA256校验和验证以防止篡改。

您可以验证二进制文件是否可用:```bash
helm-mcp-python --setup

作为服务器使用```python

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="0.0.0.0", port=8080)


### 作为客户端使用```python
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())

命令行界面```bash

stdio mode (for MCP clients like Claude Code)

helm-mcp-python

HTTP mode

helm-mcp-python --transport http --host 0.0.0.0 --port 8080

Custom binary path

helm-mcp-python --binary /usr/local/bin/helm-mcp


### 与FastMCP集成

Python包构建于 FastMCP 并返回标准的FastMCP服务器/客户端对象。您可以将其与其他FastMCP服务器组合:```python
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 按以下顺序进行二进制操作:

  1. HELM_MCP_BINARY 环境变量
  2. 包中捆绑的二进制文件 bin/ 目录
  3. 从GitHub版本自动下载(带SHA256校验和验证)
  4. helm-mcp 上 PATH

环境变量

代理将这些环境变量转发到Go子流程:

类别 变量
代理服务器 HTTP_PROXY, HTTPS_PROXY, NO_PROXY (以及小写变体)
库贝内特斯 KUBECONFIG, KUBERNETES_SERVICE_HOST, KUBERNETES_SERVICE_PORT
赫尔姆 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 中间件, 断路器,以及 坚韧所有设置均可通过以下方式配置 HELM_MCP_* 具有合理默认值的环境变量。

环境变量

变量 · 类型 · 默认值 · 描述
HELM_MCP_RETRY_ENABLED bool的。 true · 启用代理级重试中间件
HELM_MCP_RETRY_MAX_RETRIES · int · 2 · 最大重试次数
HELM_MCP_RETRY_BASE_DELAY · 浮子 · 1.0 · 初始退避延迟(秒)
HELM_MCP_RETRY_MAX_DELAY · 浮子 · 30.0 · 最大退避延迟(秒)
HELM_MCP_RETRY_BACKOFF_MULTIPLIER · 浮子 · 2.0 · 退避倍数
HELM_MCP_RATE_LIMIT_ENABLED bool的。 false · 启用令牌桶速率限制
HELM_MCP_RATE_LIMIT_MAX_RPS · 浮子 · 10.0 · 每秒最大请求数
HELM_MCP_RATE_LIMIT_BURST · int · 20 · 突发容量
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 · 浮子 · 30.0 · 半开重试前几秒
HELM_MCP_TENACITY_ENABLED bool的。 true · 启用带抖动的韧性重试
HELM_MCP_TENACITY_MAX_ATTEMPTS · int · 3 · 最大重试次数
HELM_MCP_TENACITY_MIN_WAIT · 浮子 · 0.5 · 重试之间的最短等待时间(秒)
HELM_MCP_TENACITY_MAX_WAIT · 浮子 · 10.0 · 重试之间的最大等待时间(秒)
HELM_MCP_TENACITY_MULTIPLIER · 浮子 · 1.5 · 指数退避基数
HELM_MCP_BULKHEAD_ENABLED bool的。 true · 启用并发限制器
HELM_MCP_BULKHEAD_MAX_CONCURRENT · int · 10 · 最大并发工具调用数
HELM_MCP_OTEL_ENABLED bool的。 false · 启用OpenTetry跟踪
HELM_MCP_OTEL_SERVICE_NAME · str · helm-mcp · OTel服务名称
HELM_MCP_OTEL_EXPORTER · str · console · OTel出口商(console 或 otlp)

CLI标志```bash

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


### 程序化配置```python
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")

开放遥测

FastMCP通过OpenTelemetry API发射轨迹。要接收实际的跟踪数据,请安装SDK:```bash
pip install helm-mcp[otel]


然后启用跟踪:```bash
export HELM_MCP_OTEL_ENABLED=true
export HELM_MCP_OTEL_EXPORTER=otlp        # or "console"
export HELM_MCP_OTEL_SERVICE_NAME=helm-mcp

响应有效载荷管理

大型Helm输出(清单、值、模板呈现)可能会溢出LLM上下文窗口。helm-mcp包括两层响应大小管理来防止这种情况。

响应截断

当所有工具响应超过可配置的大小限制时,它们都会自动截断。默认值为 256kb (约64K代币)。截断的响应包括指示原始大小的元数据和使用更具体查询的建议。

通过CLI标志或环境变量配置限制:```bash

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` --领导人选举数据

此净化始终处于活动状态,不能禁用,因为这些字段对LLM交互永远没有用处。原始未经消毒的数据仍然可以通过直接 `kubectl` 访问。

### 弹性原件

这 `internal/resilience` 该软件包提供了额外的生产弹性模式:

|图案|描述|
|---------|-------------|
| **断路器** |当后端不可用时,三状态(关闭/打开/半打开)模式会快速失败。可配置的故障阈值和恢复超时。 |
| **使用回退重试** |瞬态故障的指数回退和抖动。上下文感知取消和可重试错误过滤|
| **每个工具超时** |基于类别的默认超时:查询(30秒)、变异(120秒)、图表(60秒)、回购(60秒。尊重现有的上下文截止日期。 |

## 已知限制

### 需要插件验证(Helm v4 CLI)

插件操作(`helm_plugin_install`, `helm_plugin_uninstall`, `helm_plugin_update`)向系统支付费用 `helm` CLI。默认情况下,Helm v4需要插件源代码验证。不支持验证的插件(如 `helm-diff`)需要 `--verify=false`,MCP工具尚未公开。

- **变通方案**:直接通过安装插件 `helm plugin install  --verify=false`

## 安全

### 进程强化(Linux)

在Linux上运行时,helm-mcp在启动时应用进程级强化,以减少stdio传输的攻击面。作为IDE子进程运行的MCP服务器继承了完整的用户权限——这些缓解措施限制了当进程受到威胁时攻击者可以做什么。

|机制|它做什么|
|-----------|-------------|
| **PR_SET_DUMPABLE(0)** |积木 `ptrace` 连接、堆芯倾倒,以及 `/proc/pid/mem` 阅读。防止其他进程检查内存中的凭据。 |
| **能力下降** |从边界集中删除所有Linux功能。非root用户没有操作(常见情况),但在配置错误的Docker/Kubernetes环境中运行时可以防止权限升级。 |
| **凭证内存清零** | `ZeroCredentials()` 被称为via `defer` 在每个工具处理程序完成后,覆盖内存中的承载令牌和密码。这是深度防御——Go字符串是不可变的,GC可能会保留副本,但它会缩短我们代码路径中的凭据寿命。 |

硬化是 **尽最大努力,非致命** --记录故障( `--debug`)但永远不要破坏这个过程。在非Linux平台(macOS、Windows)上,通过信息日志消息跳过强化。```bash
# 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和注册中心的插件和网络I/O。系统调用表面太宽,无法在不破坏Helm SDK内部内核版本的情况下安全过滤。
命名空间隔离 该过程需要访问 ~/.kube/config、云凭据文件、DNS和网络。命名空间隔离会破坏核心功能。
C组资源限制 5分钟 pluginExecTimeout 已经限制了失控的操作,IDE管理进程生命周期。
AppArmor/SELinux配置文件 动态文件路径的维护负担很高。最好作为外部工件部署,而不是嵌入二进制文件中。

凭证清除

所有错误消息都会自动清除以删除:

  • 承载令牌(包括EKS、GKE和Azure JWT令牌)
  • 基本身份验证凭据
  • URL嵌入密码(https://user:password@host)

输入验证

每个工具处理程序调用 ValidateGlobalInput 在执行之前,确保命名空间和kubeconfig字段在每个请求上都经过验证。

安全包为以下内容提供验证器:

  • 发布名称(符合DNS-1123标准)
  • 命名空间
  • Kubeconfig文件路径(路径遍历防止、符号链接检测、敏感路径拒绝-- /etc/shadow, /proc/, /dev/, /sys/ 被封锁)
  • URL(方案验证+ SSRF保护:使用私有IP阻止的DNS解析 127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 169.254.0.0/16,以及IPv6环回/链路本地范围)
  • 文件路径(防止遍历)
  • 超时时间(最长24小时)
  • 插件名称(字母数字+破折号/下划线,没有前导破折号以防止参数注入)

文件权限

  • 存储库配置文件是用 0600 (仅限所有者读/写)
  • 配置目录是通过以下方式创建的 0700 (仅限所有者)

HTTP服务器强化

在HTTP或SSE模式下运行时:

  • ReadTimeout: 30s --防止慢速客户端攻击
  • WriteTimeout: 60s --防止连接耗尽
  • IdleTimeout: 120s --回收空闲连接
  • MaxHeaderBytes: 1MB --防止基于标头的DoS
  • 优雅关机,超时5秒

身份验证(OIDC/OAuth2)

在HTTP或SSE模式下运行时,helm-mcp支持OAuth2/OIDC身份验证,包括JWT验证、基于声明的授权和结构化审计日志记录。这与 MCP安全最佳实践.

身份验证是完全选择加入的。 当没有设置OIDC或令牌环境变量时,服务器将在没有身份验证的情况下运行(与以前的版本相同)。Stdio模式从不受身份验证配置的影响。

快速入门--Entra ID(Azure AD/ADF)```bash

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 :8080


#### 环境变量

|变量|必填|描述|
|----------|----------|-------------|
| `HELM_MCP_OIDC_ISSUER` |是(适用于OIDC)|OIDC发行人URL.Token `iss` 索赔必须匹配。 |
| `HELM_MCP_OIDC_AUDIENCE` |是(适用于OIDC)|预计 `aud` 索赔。为其他资源发行的代币被拒绝。 |
| `HELM_MCP_OIDC_JWKS_URL` |没有|JWKS端点用于签名验证。如果省略,则从发卡行自动发现。 |
| `HELM_MCP_REQUIRED_SCOPES` |否|需要逗号分隔的OAuth2作用域 `scp` 索赔。 |
| `HELM_MCP_REQUIRED_ROLES` |否|需要逗号分隔的应用程序角色 `roles` 索赔。 |
| `HELM_MCP_ALLOWED_CLIENTS` |否|允许使用逗号分隔的客户端应用程序ID `azp`/`appid` 索赔。 |
| `HELM_MCP_SESSION_TTL` |否|会话缓存不活动TTL(Go持续时间。, `5m`, `15m`).违约: `5m`. |
| `HELM_MCP_AUTH_TOKEN` |否|静态承载令牌(传统)。优先级低于OIDC。 |

#### 身份验证优先级

1. **OIDC/OAuth2** --如果 `HELM_MCP_OIDC_ISSUER` 已设置,启用JWKS的JWT验证。
1. **静态承载令牌** 要是…就好了 `HELM_MCP_AUTH_TOKEN` 设置后,使用恒定时间比较。
1. **无身份验证** --如果两者都没有设置,服务器将接受所有请求(适用于本地stdio使用)。

#### 令牌验证

每个传入的JWT都经过以下验证:

|检查|描述|
|-------|-------------|
| **签名** |根据JWKS公钥(RS256/384/512)验证RSA签名。密钥缓存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` 声称
- **缓存键**:原始承载令牌的SHA-256哈希(防止原始令牌存储在内存中)
- **滑动窗口**:每次访问都会重置不活动计时器
- **最大输入数**:10000(最老的在溢出时被驱逐)

#### 审计日志

启用OIDC身份验证后,将通过以下方式发出结构化审核事件 `slog` 对于每次身份验证尝试:```
level=INFO msg=security_audit audit.event_type=auth_success audit.principal_id=oid-123 audit.principal_name=user@example.com 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. 验证传入令牌的受众(必须与此服务器匹配)
1. 通过OBO将其兑换为针对下一个服务的新代币
1. 在新令牌的声明中保留原始用户的身份
1. 触发新的条件接收评估(如果在Entra ID中配置)

#### OBO配置```bash
# 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安全最佳实践 明确地阻止它。使用OBO,每个服务都会为自己的受众铸造一个令牌,仅限于它需要的权限。如果令牌被拦截,爆炸半径仅限于单个服务,而不是整个链。

AWS EKS和OBO支持

AWS EKS 1.34+,带OIDC

AWS EKS从EKS 1.21开始支持OIDC身份提供程序进行集群身份验证,并在1.34+版本中进行了显著改进。然而, EKS本机不支持用于Kubernetes API身份验证的Entra ID OBO流。身份验证模式不同:

模式 支持 详细信息
EKS OIDC身份提供者 是 在EKS中将Entra ID配置为OIDC提供者。用户直接使用Entra ID令牌进行身份验证,其中 aud =EKS集群。无需OBO——令牌直接为集群发放。
IRSA(服务帐户的IAM角色) 是 通过投影的服务帐户令牌进行Pod级别标识。这是M2M(客户端凭据),不是用户委托的。
EKS吊舱标识 是(EKS 1.34+) 使用EKS pod身份代理简化pod身份。M2M,而非用户委托。
OBO → Kubernetes API 部分 Entra ID OBO可以为任何注册的资源颁发令牌。如果EKS配置有作为OIDC提供商的Entra ID,并且Kubernetes API在Entra ID中注册为应用程序,则OBO颁发的令牌可以向EKS进行身份验证。需要自定义 --oidc-issuer-url, --oidc-client-id,以及 --oidc-username-claim EKS OIDC提供程序上的配置。

EKS的推荐模式:将Entra ID配置为EKS OIDC身份提供程序。MCP客户端对用户进行身份验证,并获得令牌 aud =舵手mcp。helm-mcp验证此令牌,然后执行OBO交换以获得新的令牌 aud =EKS集群OIDC客户端ID。此OBO颁发的令牌用于Kubernetes API调用,保留用户标识并启用每个用户的RBAC。

AWS实验室MCP和OBO

AWS Labs MCP服务器(例如。, awslabs/mcp)亚马逊基岩代理核心 不实现OAuth2 OBO或RFC 8693令牌交换.AgentCore使用不同的模型:

  • 用户身份传播:通过不透明的 X-Amzn-Bedrock-AgentCore-Runtime-User-Id HTTP标头-- 不 加密签名的令牌
  • 对外身份验证:OAuth授权码(3Lo)或客户端凭据(2Lo),但这些是单独的身份验证事件,不是委托身份传播
  • 代币库:存储第三方服务的刷新令牌,但这是代理范围的,不是用户委托的

这意味着AWS Labs MCP服务器无法以本机方式参与Entra ID OBO链。如果您的架构需要通过AWS托管的MCP服务器进行用户委托身份传播,则必须将OBO交换实现为自定义中间件层,或者使用helm-MCP的内置OBO支持作为参考实现。

转发代理支持

helm-mcp尊重标准代理环境变量:```bash
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


## 发展

### 先决条件

- 转到1.25+
- Python 3.12+(适用于Python包)
- golangci lint v2(可选,用于linting)

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

测试```bash

Go tests

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

Python tests (33 tests)

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


### 棉绒```bash
make lint         # Run golangci-lint + go vet
make vet          # Run go vet only

安全检查```bash

make security # Run govulncheck


### 覆盖```bash
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
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
```

贡献

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

看 贡献.md 有关以下内容的详细指南:

  • 设置您的开发环境
  • 运行测试和过梁
  • 提交拉取请求
  • 提交消息约定

社区

  • Bug报告和功能请求: GitHub问题
  • 讨论和问题: GitHub讨论
  • 发布: GitHub 发布 (每次合并到main时自动发布)

许可证

该项目根据 MIT许可证 --免费使用、修改和分发。

常见问题

8 问
答案由本站依据条目字段整理,不引用上游原文
helm MCP 怎么安装?

在客户端按下面的安装命令接入:docker run -v ~/.kube:/home/helmuser/.kube:ro helm-mcp --mode stdio。装完在客户端配置里引用同一个包或端点。

helm MCP 怎么在 Claude、Cursor、VS Code 里配置?

它的传输方式是stdio · 本地进程,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

helm MCP 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

helm MCP 需要 API Key 吗?

资料标注需要OAuth 授权认证,使用前准备好对应凭据,并按最小权限配置。

helm MCP 支持哪些客户端?

资料标注支持 Claude、Cursor、VS Code;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

helm MCP 能提供哪些能力?

资料显示约 44 个工具;能力标签包括 云原生、自然语言处理、Kubernetes、Claude。具体工具清单以官方文档为准。

helm MCP 需要什么运行环境?

运行时为 Docker;属于本地进程,需要在本机装好运行环境。

helm MCP 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-05-17。