helm MCP

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

安装

预构建二进制文件

从以下网址下载适用于您平台的最新版本 :

# 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+。

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

码头工人

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

Python包

pip install helm-mcp

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

快速开始

stdio模式（用于克劳德代码、光标等）

helm-mcp --mode stdio

HTTP模式（流式HTTP）

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

SSE模式（服务器发送事件）

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

MCP客户端配置

克劳德桌面版

添加 ~/.claude/claude_desktop_config.json:

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

克劳德代码

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

光标/风帆/VS代码

添加到MCP服务器配置中：

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

远程/HTTP客户端

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

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

可用工具（44）

发布管理（14）

图表管理（14）

存储库管理（5）

注册处/保监处（2）

搜索（2）

插件管理（4）

环境（2）

依赖关系更新（1）

Helm CLI覆盖率

完整映射每个 helm CLI命令与其helm mcp mcp工具等效。

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

Kubernetes身份验证

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

EKS（AWS）

EKS在kubeconfig中使用基于exec的身份验证。标准kubeconfig由生成 aws eks update-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": ""
}

GKE（谷歌云）

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

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

AKS（Azure）

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

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

Helm版本选择

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

{
  "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中自动可用，无需更改代码。

安装

pip install helm-mcp

需要Python 3.10+。Go二进制是 捆绑在平台专用车轮内 --不需要Go工具链。支持的平台： linux-amd64, linux-arm64, darwin-amd64, darwin-arm64, windows-amd64。首次使用时从车轮中提取二进制文件，并进行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="0.0.0.0", 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())

命令行界面

# 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服务器组合：

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子流程：

弹性配置（Python）

环境变量

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")

开放遥测

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输出（清单、值、模板呈现）可能会溢出LLM上下文窗口。helm-mcp包括两层响应大小管理来防止这种情况。

响应截断

当所有工具响应超过可配置的大小限制时，它们都会自动截断。默认值为 256kb （约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 --领导人选举数据

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

弹性原件

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

已知限制

需要插件验证（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服务器继承了完整的用户权限——这些缓解措施限制了当进程受到威胁时攻击者可以做什么。

硬化是 尽最大努力，非致命 --记录故障（ --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

已评估但未实施的机制

凭证清除

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

• 承载令牌（包括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）

# 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

环境变量

身份验证优先级

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

令牌验证

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

会话缓存

已验证的令牌缓存在内存中，以避免冗余的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. 验证传入令牌的受众（必须与此服务器匹配）
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安全最佳实践 明确地阻止它。使用OBO，每个服务都会为自己的受众铸造一个令牌，仅限于它需要的权限。如果令牌被拦截，爆炸半径仅限于单个服务，而不是整个链。

AWS EKS和OBO支持

AWS EKS 1.34+，带OIDC

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

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尊重标准代理环境变量：

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）

构建

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 (33 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
    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报告和功能请求:
• 讨论和问题:
• 发布: （每次合并到main时自动发布）

许可证

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