How the MCP Server Integrates with and Performs Helm Operations

The MCP server exposes Helm actions as standardized tools through the Model Context Protocol, registering Zod-based schemas in src/tools/helm-operations.ts and executing commands via child_process wrappers that interface with the system helm binary.

The flux159/mcp-server-kubernetes repository provides a Model Context Protocol (MCP) server that enables LLM clients to perform Kubernetes and Helm operations through a unified interface. The MCP server Helm operations architecture treats chart management as discrete tools, allowing AI assistants to install, upgrade, and uninstall Helm charts via structured JSON-RPC requests. This integration bridges the gap between conversational AI and infrastructure management by mapping high-level intents to precise helm CLI invocations.

Tool Registration and Schema Definition

Each Helm operation begins with a strictly typed input schema defined in src/tools/helm-operations.ts. The file exports three Zod-based schemas: installHelmChartSchema, upgradeHelmChartSchema, and uninstallHelmChartSchema, which validate parameters such as chart names, repositories, and values files.

These schemas are registered in the master allTools array within src/index.ts (lines 128-132), exposing them to MCP clients as install_helm_chart, upgrade_helm_chart, and uninstall_helm_chart. Each tool is marked with destructiveHint: true, enabling the server to filter them out when running in non-destructive mode via the ALLOW_ONLY_NON_DESTRUCTIVE_TOOLS environment variable.

Helm Command Implementation

The actual Helm binary interactions are wrapped in thin TypeScript functions that ensure consistent execution contexts. The executeCommand helper manages child_process.execFileSync calls with configurable timeouts, buffer sizes, and automatic injection of the KUBECONFIG environment variable.

Classic vs. Template Installation Modes

The installHelmChart function (lines 102-176 in src/tools/helm-operations.ts) supports two distinct execution paths:

• Standard Mode: Executes helm install directly against the cluster's Tiller or Helm 3 release server.
• Template Mode: When useTemplate: true is specified, the function runs helm template to generate raw YAML, then applies the manifests using kubectl apply. This mode creates temporary files under /tmp that are cleaned up immediately after execution, bypassing server-side authentication issues.

The upgradeHelmChart and uninstallHelmChart functions handle helm upgrade and helm uninstall operations respectively, both leveraging the same executeCommand infrastructure for consistent error handling and output capture.

Request Routing and Execution Flow

When an MCP client sends a CallToolRequest to the server, the central dispatcher in src/index.ts (lines 19-45) matches the tool name against registered handlers. The execution flow follows this sequence:

Client CallToolRequest(name="install_helm_chart")
    ↓
src/index.ts dispatcher validates schema
    ↓
Routes to installHelmChart(params)
    ↓
Executes helm binary via executeCommand()
    ↓
Returns HelmResponse JSON from src/models/helm-models.ts

The response structure is defined in src/models/helm-models.ts, ensuring consistent typing across the tool interface.

Multi-Cluster Support and Security Controls

The integration supports complex multi-cluster environments through contextParameter and namespaceParameter, imported from src/models/common-parameters.ts. These parameters allow callers to specify alternative kubeconfig contexts and target namespaces, enabling a single MCP server instance to manage workloads across multiple Kubernetes clusters.

Template mode provides additional security flexibility for restricted environments. By generating manifests locally and applying them with kubectl, this mode avoids Helm release server authentication requirements while maintaining full audit trails through the MCP request/response logs.

Practical Usage Examples

Programmatic Client Integration

import { Client } from "@modelcontextprotocol/sdk/client";

async function installDemoChart() {
  const client = new Client({ /* transport config */ });
  const result = await client.callTool("install_helm_chart", {
    name: "demo-release",
    chart: "bitnami/nginx",
    repo: "https://charts.bitnami.com/bitnami",
    namespace: "demo-ns",
    values: { service: { type: "LoadBalancer" } },
    useTemplate: false,
    createNamespace: true,
  });
  console.log("Helm install result:", result);
}

CLI Usage with mcp-chat

bun run chat install_helm_chart \
    --name myapp \
    --chart oci://ghcr.io/flux159/charts/myapp \
    --namespace production \
    --repo https://myrepo.example.com/charts \
    --values '{"replicaCount":3}'

Template Mode for Air-Gapped Environments

await client.callTool("install_helm_chart", {
  name: "templated-app",
  chart: "./charts/myapp",
  namespace: "default",
  useTemplate: true,
  valuesFile: "./overrides.yaml",
});

Summary

• Schema-driven validation: Helm operations use Zod schemas in src/tools/helm-operations.ts to ensure type safety for chart installations, upgrades, and removals.
• Dual execution modes: The server supports both standard helm install and template-based (helm template + kubectl apply) deployments to accommodate different authentication models.
• Cluster context awareness: Parameters from src/models/common-parameters.ts enable targeting specific kubeconfig contexts and namespaces for multi-cluster management.
• Safety controls: All Helm tools carry destructiveHint: true metadata, allowing automatic filtering in non-destructive server modes.
• Consistent execution layer: The executeCommand helper standardizes process spawning, timeout handling, and environment variable injection across all Helm operations.

Frequently Asked Questions

How does the MCP server handle Helm authentication?

The server delegates authentication to the underlying helm and kubectl binaries by passing the KUBECONFIG environment variable through the executeCommand helper. For environments with restrictive Helm server access, enabling useTemplate: true bypasses Tiller or Helm release server authentication by generating manifests locally and applying them via kubectl.

Can I target multiple Kubernetes clusters with the same MCP server?

Yes. The contextParameter and namespaceParameter options imported from src/models/common-parameters.ts allow each tool call to specify a different kubeconfig context. This enables a single MCP server instance to manage Helm releases across development, staging, and production clusters without restarting the service.

What happens when the server runs in non-destructive mode?

When the ALLOW_ONLY_NON_DESTRUCTIVE_TOOLS environment variable is set, the server filters out any tool marked with destructiveHint: true. Since install_helm_chart, upgrade_helm_chart, and uninstall_helm_chart all carry this flag, they become unavailable to clients, preventing accidental infrastructure modifications in read-only deployments.

Where does template mode store generated manifests?

Template mode writes temporary YAML files to /tmp during the helm template execution phase. These files are immediately cleaned up after kubectl apply completes, regardless of success or failure, ensuring no sensitive manifest data persists on the filesystem after the operation concludes.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}