Helm Mcp— agent skill

<p align="center"> <img src="assets/helm-mcp-logo.svg" width="500" alt="Helm MCP"> </p>

<p align="center"> <a href="https://github.com/SCGIS-Wales/helm-mcp/actions/workflows/ci.yml"><img src="https://github.com/SCGIS-Wales/helm-mcp/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI/CD Pipeline"></a> <a href="https://goreportcard.com/report/github.com/SCGIS-Wales/helm-mcp"><img src="https://img.shields.io/badge/go%20report-A+-brightgreen.svg" alt="Go Report Card"></a> <a href="https://pypi.org/project/helm-mcp/"><img src="https://img.shields.io/pypi/v/helm-mcp" alt="PyPI version"></a> <a href="https://pypi.org/project/helm-mcp/"><img src="https://img.shields.io/pypi/pyversions/helm-mcp" alt="Python versions"></a> <a href="https://pypistats.org/packages/helm-mcp"><img src="https://img.shields.io/pypi/dm/helm-mcp" alt="Downloads"></a> <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a> </p>

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

<p align="center"> <em>Use natural language to manage your Kubernetes deployments.</em><br> 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. </p>

Table of Contents

• Why helm-mcp?
• Installation
• Quick Start
• MCP Client Configuration
• Available Tools
• Helm CLI Coverage
• Kubernetes Authentication
• Helm Version Selection
• Python Package
• Resilience Configuration (Python)
• Response Payload Management
• Known Limitations
• Security
• Authentication (OIDC/OAuth2)
• On-Behalf-Of (OBO) Token Exchange
• Development
• Architecture
• Contributing
• Community
• License

Why helm-mcp?

• 44 MCP tools covering every Helm CLI command (minus shell completion and help)
• Dual Helm SDK support — Helm v3 and v4 via native Go SDK (not CLI wrappers)
• Three transport modes — stdio (default), HTTP (Streamable HTTP), SSE
• Cloud provider ready — EKS, GKE, AKS kubeconfig formats work out of the box
• Security first — Linux process hardening, credential memory zeroing, input validation, path traversal prevention
• Python wrapper — FastMCP-based proxy that auto-discovers all tools
• Forward proxy support — respects HTTP_PROXY, HTTPS_PROXY, NO_PROXY

Installation

Pre-built Binaries

Download the latest release for your platform from 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

Build from Source

Requires Go 1.25+.

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 Package

pip install helm-mcp

See Python Package below for full details.

Quick Start

stdio mode (for Claude Code, Cursor, etc.)

helm-mcp --mode stdio

HTTP mode (Streamable HTTP)

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

SSE mode (Server-Sent Events)

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

MCP Client Configuration

Claude Desktop

Add to ~/.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

Add to your MCP server configuration:

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

Remote / HTTP Clients

Start the server in HTTP mode, then connect any MCP-compatible client to the endpoint:

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

Available Tools (44)

Release Management (14)

Chart Management (14)

Repository Management (5)

Registry / OCI (2)

Search (2)

Plugin Management (4)

Environment (2)

Dependency Update (1)

Helm CLI Coverage

Complete mapping of every helm CLI command to its helm-mcp MCP tool equivalent.

44 of 44 operational Helm commands are covered. The only excluded commands (completion, help) are shell utilities that have no meaning in an MCP context.

Kubernetes Authentication

Every tool accepts these authentication fields via the GlobalInput:

EKS (AWS)

EKS uses exec-based authentication in kubeconfig. The standard kubeconfig generated by aws eks update-kubeconfig works out of the box:

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

Or with direct token authentication:

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

GKE (Google Cloud)

GKE kubeconfig generated by gcloud container clusters get-credentials works out of the box:

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

AKS (Azure)

AKS kubeconfig generated by az aks get-credentials works out of the box:

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

Helm Version Selection

Every tool supports a helm_version field to select between Helm v3 and v4:

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

• "v4" (default) — Uses Helm v4 SDK with Server-Side Apply, WASM plugins, label selectors
• "v3" — Uses Helm v3 SDK for backward compatibility

v4-Only Features

These fields are only available when using helm_version: "v4":

• server_side_apply — Use Kubernetes server-side apply
• take_ownership — Skip Helm annotation checks
• rollback_on_failure — Auto-rollback on install failure
• hide_secret — Hide secrets in dry-run output
• force_conflicts — Force conflict resolution
• selector — Label selector for list operations
• show_resources — Show resources table in status
• reset_then_reuse_values — Reset then reuse values in upgrade

Python Package

A Python wrapper is available that uses FastMCP to create a transparent proxy around the helm-mcp Go binary. New tools added to the Go binary are automatically available in Python without code changes.

Installation

pip install helm-mcp

Requires Python 3.12+. The Go binary is bundled inside platform-specific wheels — no Go toolchain is required. Supported platforms: linux-amd64, linux-arm64, darwin-amd64, darwin-arm64, windows-amd64. The binary is extracted from the wheel on first use, with SHA256 checksum verification to protect against tampering.

You can verify the binary is available:

helm-mcp-python --setup

Usage as a Server

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)

Usage as a Client

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
helm-mcp-python --transport http --host 0.0.0.0 --port 8080

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

Integrating with FastMCP

The Python package is built on FastMCP and returns standard FastMCP server/client objects. You can compose it with other FastMCP servers:

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

Binary Discovery

The Python package locates the helm-mcp Go binary in this order:

1. HELM_MCP_BINARY environment variable
2. Bundled binary in the package bin/ directory
3. Auto-download from GitHub Releases (with SHA256 checksum verification)
4. helm-mcp on PATH

Environment Variables

The proxy forwards these environment variables to the Go subprocess:

Resilience Configuration (Python)

The Python package includes a comprehensive resilience stack built on FastMCP middleware, circuitbreaker, and tenacity. All settings are configurable via HELM_MCP_* environment variables with sensible defaults.

Environment Variables

CLI Flags

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

Programmatic Configuration

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 emits traces via the OpenTelemetry API. To receive actual trace data, install the SDK:

pip install helm-mcp[otel]

Then enable tracing:

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

Response Payload Management

Large Helm outputs (manifests, values, template renders) can overflow LLM context windows. helm-mcp includes two layers of response size management to prevent this.

Response Truncation

All tool responses are automatically truncated when they exceed a configurable size limit. The default is 256 KB (~64K tokens). Truncated responses include metadata indicating the original size and a suggestion to use more specific queries.

Configure the limit via CLI flag or environment variable:

# 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

The CLI flag takes precedence over the environment variable.

Manifest Sanitisation

Tools that return Kubernetes YAML (helm_get_manifest, helm_get_all, helm_get_hooks, helm_template) automatically strip noisy fields before returning results. This typically reduces manifest sizes by 40-60% without losing meaningful information.

Fields stripped:

• metadata.managedFields — internal Kubernetes bookkeeping (often the largest single field)
• kubectl.kubernetes.io/last-applied-configuration — redundant copy of the entire object
• deployment.kubernetes.io/revision — internal controller annotation
• control-plane.alpha.kubernetes.io/leader — leader election data

This sanitisation is always active and cannot be disabled, as these fields are never useful for LLM interactions. The original unsanitised data remains available through direct kubectl access.

Resilience Primitives

The internal/resilience package provides additional production resilience patterns:

Known Limitations

Plugin Verification Required (Helm v4 CLI)

Plugin operations (helm_plugin_install, helm_plugin_uninstall, helm_plugin_update) shell out to the system helm CLI. Helm v4 requires plugin source verification by default. Plugins that do not support verification (like helm-diff) need --verify=false, which the MCP tool does not yet expose.

• Workaround: Install plugins directly via helm plugin install <url> --verify=false

Security

Process Hardening (Linux)

When running on Linux, helm-mcp applies process-level hardening at startup to reduce the attack surface of the stdio transport. MCP servers running as IDE child processes inherit full user privileges — these mitigations limit what an attacker can do if the process is compromised.

Hardening is best-effort and non-fatal — failures are logged (with --debug) but never crash the process. On non-Linux platforms (macOS, Windows), hardening is skipped with an informational log message.

# 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

#### Mechanisms Evaluated but Not Implemented

Credential Scrubbing

All error messages are automatically scrubbed to remove:

• Bearer tokens (including EKS, GKE, and Azure JWT tokens)
• Basic authentication credentials
• URL-embedded passwords (https://user:password@host)

Input Validation

Every tool handler calls ValidateGlobalInput before executing, ensuring namespace and kubeconfig fields are validated on every request.

The security package provides validators for:

• Release names (DNS-1123 compliant)
• Namespace names
• Kubeconfig file paths (path traversal prevention, symlink detection, sensitive path rejection — /etc/shadow, /proc/, /dev/, /sys/ are blocked)
• URLs (scheme validation + SSRF protection: DNS resolution with private IP blocking for 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, and IPv6 loopback/link-local ranges)
• File paths (traversal prevention)
• Timeout durations (max 24h)
• Plugin names (alphanumeric + dashes/underscores, no leading dash to prevent argument injection)

File Permissions

• Repository configuration files are written with 0600 (owner read/write only)
• Config directories are created with 0700 (owner only)

HTTP Server Hardening

When running in HTTP or SSE mode:

• ReadTimeout: 30s — prevents slow client attacks
• WriteTimeout: 60s — prevents connection exhaustion
• IdleTimeout: 120s — reclaims idle connections
• MaxHeaderBytes: 1MB — prevents header-based DoS
• Graceful shutdown with 5-second timeout

Authentication (OIDC/OAuth2)

When running in HTTP or SSE mode, helm-mcp supports OAuth2/OIDC authentication with JWT validation, claims-based authorization, and structured audit logging. This aligns with the MCP Security Best Practices.

Authentication is fully opt-in. When no OIDC or token environment variables are set, the server runs without authentication (same as previous versions). Stdio mode is never affected by authentication configuration.

#### Quick Start — 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 :8080

#### Environment Variables

#### Authentication Priority

1. OIDC/OAuth2 — if HELM_MCP_OIDC_ISSUER is set, JWT validation with JWKS is enabled.
2. Static bearer token — if only HELM_MCP_AUTH_TOKEN is set, constant-time comparison is used.
3. No auth — if neither is set, the server accepts all requests (suitable for local stdio usage).

#### Token Validation

Every incoming JWT is validated for:

#### Session Cache

Validated tokens are cached in-memory to avoid redundant JWKS lookups:

• Inactivity TTL: 5 minutes by default (configurable via HELM_MCP_SESSION_TTL, e.g., 5m, 10m, 1h)
• Token expiry: Cached tokens are never used beyond their exp claim
• Cache key: SHA-256 hash of the raw bearer token (prevents raw token storage in memory)
• Sliding window: Each access resets the inactivity timer
• Maximum entries: 10,000 (oldest evicted on overflow)

#### Audit Logging

When OIDC authentication is enabled, structured audit events are emitted via slog for every authentication attempt:

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

Audit events include: principal ID/name, tenant ID, client app ID, scopes, roles, token ID, session ID, action, resource, result, duration, and remote address. Enable --debug for full audit visibility, or configure your log aggregator to capture security_audit messages.

On-Behalf-Of (OBO) Token Exchange

When helm-mcp needs to call a downstream API (such as the Kubernetes API) on behalf of the authenticated user, it exchanges the incoming token for a new one scoped to that downstream service. This avoids forwarding the original token, which could be misused if the downstream service is compromised or if the token's audience doesn't match.

#### How It Works

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         │

Each hop in the chain:

1. Validates the incoming token's audience (must match this server)
2. Exchanges it via OBO for a new token targeted at the next service
3. Preserves the original user's identity in the new token's claims
4. Triggers a fresh Conditional Access evaluation (if configured in Entra ID)

#### OBO Configuration

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

#### Why Not Forward the Token?

Forwarding a user's token to downstream services is tempting but problematic. The MCP Security Best Practices explicitly discourages it. With OBO, each service gets a token minted for its own audience, scoped to only the permissions it needs. If a token is intercepted, the blast radius is limited to a single service rather than the entire chain.

AWS EKS and OBO Support

#### AWS EKS 1.34+ with OIDC

AWS EKS supports OIDC identity providers for cluster authentication starting from EKS 1.21, with significant improvements in 1.34+. However, EKS does not natively support the Entra ID OBO flow for Kubernetes API authentication. The authentication patterns differ:

Recommended pattern for EKS: Configure Entra ID as the EKS OIDC identity provider. The MCP client authenticates the user and obtains a token with aud = helm-mcp. helm-mcp validates this token, then performs an OBO exchange to get a new token with aud = EKS cluster OIDC client ID. This OBO-issued token is used for Kubernetes API calls, preserving user identity and enabling per-user RBAC.

#### AWS Labs MCP and OBO

AWS Labs MCP servers (e.g., awslabs/mcp) and Amazon Bedrock AgentCore do not implement OAuth2 OBO or RFC 8693 Token Exchange. AgentCore uses a different model:

• User identity propagation: Via an opaque X-Amzn-Bedrock-AgentCore-Runtime-User-Id HTTP header — not a cryptographically signed token
• Outbound authentication: OAuth Authorization Code (3Lo) or Client Credentials (2Lo), but these are separate auth events, not delegated identity propagation
• Token Vault: Stores refresh tokens for third-party services, but this is agent-scoped, not user-delegated

This means AWS Labs MCP servers cannot participate in an Entra ID OBO chain natively. If your architecture requires user-delegated identity propagation through AWS-hosted MCP servers, you must implement OBO exchange as a custom middleware layer, or use helm-mcp's built-in OBO support as a reference implementation.

Forward Proxy Support

helm-mcp respects standard proxy environment variables:

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

Development

Prerequisites

• Go 1.25+
• Python 3.12+ (for the Python package)
• golangci-lint v2 (optional, for linting)

Build

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

Test

# 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/

Lint

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

Security Check

make security     # Run govulncheck

Coverage

make coverage     # Generate coverage report (coverage.html)

Architecture

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

Contributing

We welcome contributions from the community! Whether it's bug reports, feature requests, documentation improvements, or code contributions — all help is appreciated.

See CONTRIBUTING.md for detailed guidelines on:

• Setting up your development environment
• Running tests and linters
• Submitting pull requests
• Commit message conventions

Community

• Bug reports & feature requests: GitHub Issues
• Discussions & questions: GitHub Discussions
• Releases: GitHub Releases (auto-published on every merge to main)

License

This project is licensed under the MIT License — free to use, modify, and distribute.