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 按以下顺序进行二进制操作:
HELM_MCP_BINARY环境变量- 包中捆绑的二进制文件
bin/目录 - 从GitHub版本自动下载(带SHA256校验和验证)
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-IdHTTP标头-- 不 加密签名的令牌 - 对外身份验证: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许可证 --免费使用、修改和分发。
