Serveur MCP helm-python-ai
Commit 9 nov. 2026Manage Kubernetes Helm releases from Claude or any MCP client using an autonomous AI agent and safety-tiered tools.
Aussi connu sous shivamkumar99/helm-python-ai
- Étoiles
- 0
- Outils
- —
- Téléchargements, 30 jours
- —
- Dernière version
- —
- Dernier commit
- 9 nov. 2026
- Licence
- Apache-2.0
Qu'est-ce que helm-python-ai MCP ?
Manage Kubernetes Helm releases from Claude or any MCP client using an autonomous AI agent and safety-tiered tools.
Résumé généré à partir du README du projet
À propos du MCP server helm-python-ai
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.
Ce que vous pouvez faire avec
- 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.
Extrait du README du projet. Chaque cas d'utilisation est vérifié par rapport à une citation du document.
Configuration
ANTHROPIC_API_KEY
| Nom | Description | Type |
|---|---|---|
| ANTHROPIC_API_KEY | — |
Vérifications automatisées
Exécuté le 15 nov. 2026Rapport complet →Pas encore vérifié. Un serveur nécessite un score de 80, aucune faille sérieuse et suffisamment de données pour que nous puissions effectuer les vérifications. Fonctionnement des vérifications · Ce qu'il faut corriger pour gagner des points
- Dépôt source lié et accessibleshivamkumar99/helm-python-ai is public and reachablegithub.com/shivamkumar99/helm-python-ai ↗Réussi
- Le nom du package correspond au dépôt sourceNon vérifié
- Provenance du build (attestation Sigstore)Non vérifié
- Licence open source (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Réussi
- Commit ou version publiée au cours de l'année écouléeLast commit or release 2026-11-09github.com/shivamkumar99/helm-python-ai ↗Réussi
- OpenSSF ScorecardNon vérifié
- Nom du package non proche d'un package populaireNon vérifié
- Aucun avis critique dans le package ou ses dépendancesNon vérifié
- Aucune instruction cachée destinée au modèle0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersRéussi
- Les outils destructifs sont étiquetésNon vérifié
- Le point de terminaison distant répond à la poignée de main MCPNon vérifié
README
Voir sur GitHubhelm-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
Questions sur helm-python-ai MCP
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.