helm-python-ai MCP server
Commit 9. Nov. 2026Manage Kubernetes Helm releases from Claude or any MCP client using an autonomous AI agent and safety-tiered tools.
Auch bekannt als shivamkumar99/helm-python-ai
- Stars
- 0
- Tools
- —
- Downloads, 30 Tage
- —
- Neueste Version
- —
- Letzter Commit
- 9. Nov. 2026
- Lizenz
- Apache-2.0
Was ist helm-python-ai MCP?
Manage Kubernetes Helm releases from Claude or any MCP client using an autonomous AI agent and safety-tiered tools.
Zusammenfassung generiert aus dem README des Projekts
Über helm-python-ai MCP server
Managing Kubernetes deployments through natural language is possible with helm-python-ai, which provides an MCP server and an autonomous agent for Helm. Developers can use the helm-ai-mcp server within Claude Desktop or Claude Code to interact with Helm releases using fifteen specialized tools. The system operates locally via stdio transport and uses your existing kubeconfig for cluster access, meaning no separate helm or kubectl binaries are required because it binds directly to the official Go SDK via a Python wrapper.
Safety is a core component of the architecture, utilizing three distinct tiers of access. Read tools are always available, while write operations like helm_install_release default to a dry-run mode unless specific environment variables are enabled. Destructive actions such as helm_uninstall_release require both an environment flag and an exact name confirmation. This tiered approach ensures that an AI agent can investigate deployment issues or propose changes without accidentally modifying your production environment without explicit permission.
Was du damit machen kannst
- 1Troubleshoot failing deploymentsAsk the autonomous agent to investigate why a specific release is failing in a production namespace.
- 2Audit Helm operationsMaintain a structured record of every tool invocation and safety decision made by the AI.
Geschrieben aus dem README des Projekts. Jeder Use Case wurde gegen ein Zitat daraus geprüft.
Konfiguration
ANTHROPIC_API_KEY
| Name | Beschreibung | Typ |
|---|---|---|
| ANTHROPIC_API_KEY | — |
Automatisierte Checks
Geluften am 15. Nov. 2026Vollständiger Bericht →Noch nicht verifiziert. Ein Server benötigt einen Score von 80, keine kritischen Befunde und genug Daten für unsere Prüfung. Wie die Checks funktionieren · Was du für mehr Punkte verbessern kannst
- Source Repository verknüpft und erreichbarshivamkumar99/helm-python-ai is public and reachablegithub.com/shivamkumar99/helm-python-ai ↗Bestanden
- Paket nennt dieses Repository als QuelleNicht geprüft
- Build-Provenienz (Sigstore-Attestierung)Nicht geprüft
- Open Source Lizenz (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Bestanden
- Commit oder Release im letzten JahrLast commit or release 2026-11-09github.com/shivamkumar99/helm-python-ai ↗Bestanden
- OpenSSF ScorecardNicht geprüft
- Package-Name ähnelt keinem populären PackageNicht geprüft
- Keine kritischen Advisories im Paket oder seinen AbhängigkeitenNicht geprüft
- Keine versteckten Anweisungen an das Modell0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersBestanden
- Destruktive Tools sind markiertNicht geprüft
- Remote-Endpoint beantwortet den MCP-HandshakeNicht geprüft
README
Auf GitHub ansehenhelm-python-ai — MCP Server and AI Agent for Helm
A Model Context Protocol (MCP) server and an
autonomous AI agent for Helm, the Kubernetes package
manager. Manage Helm releases from Claude Code, Claude Desktop, or any MCP
client — or hand a plain-language mission to an LLM agent that investigates
and operates your deployments — with safety tiers, dry-run defaults, and a
structured audit trail. Built in Python on
helm-python-sdk, which
binds Helm's official Go SDK directly: no helm binary, no kubectl, no
shelling out.
Two fronts share one safety-tiered tool layer:
| Command | What it is | Runtime |
|---|---|---|
helm-ai-mcp |
An MCP server exposing Helm operations to any MCP client (Claude Code, Claude Desktop, …) | mcp ≥ 2 |
helm-ai-agent |
An autonomous agent that investigates and operates releases from a plain-language mission | anthropic |
helm (Go SDK) → helm-c-sdk (C ABI) → helm-python-sdk (ctypes) → helm-python-ai
├─ helm-ai-mcp (MCP server)
└─ helm-ai-agent (agent CLI)
Install
pip install "helm-python-ai[all]" # both fronts
pip install "helm-python-ai[server]" # MCP server only
pip install "helm-python-ai[agent]" # agent only
Python ≥ 3.10. The native Helm library ships inside the helm-python-sdk
wheel — nothing else to install.
The MCP server
Register in your MCP client (stdio transport):
{
"mcpServers": {
"helm": {
"command": "helm-ai-mcp"
}
}
}
Fifteen tools in three tiers:
- Read (always available):
helm_list_releases,helm_release_status,helm_release_manifest,helm_release_history,helm_release_values,helm_show_chart,helm_template_chart,helm_lint_chart,helm_search_repository,helm_chart_tags,helm_versions. - Write (dry-run by default):
helm_install_release,helm_upgrade_release. They run as server-side dry runs unless called withapply=trueand the server environment setsHELM_AI_ALLOW_WRITES=1. - Destructive (double-gated):
helm_uninstall_release,helm_rollback_release. They requireconfirm=<release name>echoed exactly andHELM_AI_ALLOW_DESTRUCTIVE=1in the server environment.
Cluster access uses the standard kubeconfig resolution (KUBECONFIG, then
~/.kube/config, then in-cluster).
Live feedback
Long-running tools (installs, upgrades, registry operations) are async and send MCP progress notifications every few seconds while they run — elapsed time plus the Helm SDK's own live log line ("waiting for resources…") — so the host can show real activity instead of a call that looks stuck.
Releases dashboard (MCP Apps)
helm_list_releases ships an MCP Apps
(SEP-1865) UI: hosts that support the extension — Claude among them —
render the releases as an interactive table (status badges, revisions,
chart versions) directly in the conversation. Hosts without the extension
see the same JSON text as before; nothing is lost.
Docker
docker build -t helm-ai-mcp .
The build installs helm-python-sdk straight from PyPI — prebuilt wheels
exist for amd64 and arm64, so nothing compiles — on Docker Hardened
Images (digest-pinned, Debian/glibc): a -dev stage assembles the venv
and the hardened runtime variant ships it (non-root, no shell, no
installers, near-zero CVEs). Pulling dhi.io needs a free Docker
login.
Run it with least privilege (no capabilities, no privilege escalation, read-only root filesystem, tmpfs scratch space):
{
"mcpServers": {
"helm": {
"command": "docker",
"args": ["run", "-i", "--rm", "--init",
"--read-only", "--cap-drop", "ALL",
"--security-opt", "no-new-privileges",
"--tmpfs", "/tmp", "--tmpfs", "/home/nonroot",
"-v", "/home/you/.kube/config:/home/nonroot/.kube/config:ro",
"helm-ai-mcp"]
}
}
}
docker-compose.yml wraps the same image for docker compose run --rm helm-mcp (compose run, not up: stdio servers are launched by their
client) with the same hardening baked in (cap_drop: [ALL],
no-new-privileges, read_only, tmpfs mounts, pids_limit). Pass
-e HELM_AI_ALLOW_WRITES=1 / -e HELM_AI_ALLOW_DESTRUCTIVE=1 only when
you mean it, and prefer mounting a kubeconfig whose RBAC matches the tier
you enabled.
The agent
export ANTHROPIC_API_KEY=... # or an active `ant auth` profile
helm-ai-agent "why is release payments-api failing in namespace prod?"
The agent investigates with the read-only tools first, cites evidence (revisions, values diffs, manifest details), dry-runs any change it proposes, and asks at the keyboard before applying or destroying anything:
→ list_releases {"namespace": "prod"}
→ release_history {"name": "payments-api", "namespace": "prod"}
→ release_values {"name": "payments-api", "revision": 6}
APPROVAL NEEDED: helm upgrade payments-api ./charts/payments (namespace=prod)
Proceed? [y/N]
--yes auto-approves gated operations (for scripted use, together with the
environment gates); --model selects the Claude model (default
claude-opus-5); -v/--verbose streams the Helm SDK's own log lines to
stderr while operations run.
Security model
The design follows the MCP security best practices and the OWASP GenAI Practical Guide for Secure MCP Server Development (v1.0, Feb 2026):
- stdio transport only. The server is a local child process of its MCP client; it never opens a network socket, so the remote-transport attack classes (token passthrough, confused deputy, session hijacking) do not arise. Do not put it behind an HTTP proxy without adding authentication.
- Structured, schema-validated invocation. Every tool has a typed JSON schema; values documents are size-capped (1 MB) and must parse to a JSON object; release names are validated by Helm's own rules before use.
- Least privilege by default. Read tools are ungated; writes are dry-run unless explicitly enabled; destructive operations are double-gated (exact-name confirmation + a separate environment flag). For defense in depth, run the server with a kubeconfig whose RBAC matches the tier you enabled — a read-only account when the gates are off.
- Human in the loop. The agent pauses for keyboard approval on every write/destructive operation; over MCP (no terminal), the environment gates are the authorization channel and the client's own approval UI governs tool use.
- No secrets in the model's reach. No tool accepts or returns credentials. Registry and cluster credentials come from Helm's and Kubernetes' own configuration files; there is no login tool, and error messages carry Helm's detail strings, not tracebacks.
- Untrusted data stays data. Chart READMEs, notes, values, and manifests are cluster-controlled input. The agent's system prompt pins them as data-not-instructions; treat MCP tool output the same way in your client.
- Resource limits. Install/upgrade waits are capped (300 s default) and tool output is truncated at 200 K characters with an explicit marker, so a wedged rollout or a huge manifest cannot hang the process or flood the model's context.
- Audit trail. Every allow/refuse decision and every mutating operation (with parameters) is logged to stderr, where the MCP host captures it — stdout stays reserved for protocol framing.
Observability & audit
Instrumentation is vendor-neutral OpenTelemetry; no backend is bundled.
- Tracing — the MCP SDK emits a span per inbound message
(
tools/call helm_install_release, GenAIexecute_toolattributes, W3C trace-context propagation from the caller), and the tool layer adds a nested span per operation. The agent wraps each mission in aninvoke_agentspan carryinggen_ai.usage.input_tokens/output_tokensand turn count. Export activates only when the standardOTEL_EXPORTER_OTLP_ENDPOINTis set and theobservabilityextra is installed (pip install helm-python-ai[observability]); point it at any OTLP backend (Grafana/Tempo, Jaeger, Langfuse, Datadog, ...). - Audit trail — every tool invocation (with an allowlisted argument
snapshot; values payloads are recorded as sizes only, never content),
every safety allow/refuse decision, every MCP request outcome, and each
agent mission produce structured JSON events on the
helm_ai.auditlogger (stderr) and, whenHELM_AI_AUDIT_LOG=/path/file.jsonlis set, an append-only JSONL file. Events carry the active trace/span IDs, so audit records and traces cross-reference. - Metrics —
helm_ai.tool.calls(by tool and outcome) and ahelm_ai.tool.durationhistogram flow through the same OTLP pipeline; refusal spikes and error rates are the signals worth alerting on.
Development
python -m venv .venv && .venv/bin/pip install -e ".[dev]"
.venv/bin/pytest # offline; cluster tests auto-skip
.venv/bin/ruff check src tests
License
helm-python-ai MCP Fragen
How does the server handle destructive operations like uninstalls?
Destructive operations are double-gated, requiring both an exact name confirmation and the HELM_AI_ALLOW_DESTRUCTIVE environment variable to be set.
Can I use this with Claude Desktop?
Yes, you can register the MCP server in your Claude Desktop configuration using the stdio transport.
What happens if I try to install or upgrade a release?
By default, write operations run as server-side dry runs unless you explicitly set apply=true and enable the HELM_AI_ALLOW_WRITES environment variable.