KubeCraft MCP Server

A Model Context Protocol (MCP) server that gives AI assistants (Claude, Cursor, etc.) full visibility and control over Kubernetes clusters.

Features (73 Community tools · 140 with KubeCraft Pro)

The open-source Community Edition (this repository, MIT) ships 73 tools. The separately licensed KubeCraft Pro add-on registers 67 more (140 total); those are marked Pro below and are not included in this repository or the Community image.

Further roadmap items (HTTP MCP transport, deeper GitOps) are in docs/ROADMAP.md.

Related MCP server: Kubernetes MCP Server

Diagram & Visual Rendering

KubeCraft returns visual content using multiple MCP content types, with automatic browser fallback for clients that don't render visuals inline.

Auto-open behavior: When KUBECRAFT_OUTPUT_DIR is configured and writable, rendered PNGs and 3D HTML files are saved to disk and automatically opened in the user's default browser or image viewer. Inside Docker containers, auto-open works only when the container can reach the host display (e.g. via X11 forwarding or host networking); otherwise, open the saved files from the host-mounted output directory.

Kubernetes Distribution Compatibility

KubeCraft uses the standard Kubernetes Python client and communicates directly with the K8s API server — no kubectl or other CLI wrappers required.

Quick Start

Build the Docker image

docker build -t kubecraft-mcp:latest .

Configure in Cursor

Create or edit .cursor/mcp.json in your project:

{
  "mcpServers": {
    "kubecraft": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i", "--network=host",
        "-v", "/home/<user>/.kube:/home/mcp/.kube:ro",
        "-e", "KUBECONFIG=/home/mcp/.kube/config",
        "kubecraft-mcp:latest"
      ]
    }
  }
}

Windows (WSL kubeconfig):

{
  "mcpServers": {
    "kubecraft": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "C:\\Users\\<user>\\.kube:/home/mcp/.kube:ro",
        "-e", "KUBECONFIG=/home/mcp/.kube/config",
        "kubecraft-mcp:latest"
      ]
    }
  }
}

3D topology viewer (HTTP link, KubeCraft Pro): The Viewer URL works only while the Kubecraft process is running. If you run a one-off python -c locally, the server exits immediately and the link will show connection refused. On Docker Desktop (Windows/macOS), --network=host does not publish the container's loopback to your host browser like it does on Linux; prefer opening the saved HTML file from KUBECRAFT_OUTPUT_DIR, or publish a fixed port, for example add to args: "run", "--rm", "-i", "-p", "8765:8765", plus -e, KUBECRAFT_VIEWER_BIND=0.0.0.0:8765, -e, KUBECRAFT_VIEWER_EXPOSE=1, then use http://127.0.0.1:8765 plus the path from the tool output (copy it exactly; the token is case-sensitive).

Configure in Claude Desktop

Claude Desktop doesn't render MCP ImageContent or EmbeddedResource inline, so diagrams are saved to a shared folder on your machine and automatically opened in your default browser/viewer. Open (or create) %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

Windows:

{
  "mcpServers": {
    "kubecraft": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i", "--network=host",
        "-v", "C:\\Users\\<user>\\.kube:/home/mcp/.kube:ro",
        "-v", "C:\\Users\\<user>\\kubecraft-diagrams:/output",
        "-e", "KUBECONFIG=/home/mcp/.kube/config",
        "-e", "KUBECRAFT_OUTPUT_DIR=/output",
        "kubecraft-mcp:latest"
      ]
    }
  }
}

Rendered PNG diagrams and 3D topology HTML files will appear in C:\Users\<user>\kubecraft-diagrams\ and auto-open in your browser.

macOS / Linux:

{
  "mcpServers": {
    "kubecraft": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i", "--network=host",
        "-v", "/home/<user>/.kube:/home/mcp/.kube:ro",
        "-v", "/home/<user>/kubecraft-diagrams:/output",
        "-e", "KUBECONFIG=/home/mcp/.kube/config",
        "-e", "KUBECRAFT_OUTPUT_DIR=/output",
        "kubecraft-mcp:latest"
      ]
    }
  }
}

Configure in Claude Code

claude mcp add kubecraft \
  -- docker run --rm -i --network=host \
  -v ~/.kube:/home/mcp/.kube:ro \
  -e KUBECONFIG=/home/mcp/.kube/config \
  kubecraft-mcp:latest

Built-in Chat UI (Web mode)

KubeCraft ships with a full React/TypeScript chat UI bundled in the same Docker image. It exposes the full tool surface (73 Community tools, or 140 with KubeCraft Pro installed) as a conversational interface backed by your choice of LLM (Claude, OpenAI, or Azure OpenAI) — the LLM decides when to call MCP tools and the UI streams the results back with markdown, embedded PNG diagrams, and (with Pro) an interactive 3D topology viewer.

Pages

• Chat — streaming conversation with expandable tool-invocation cards, image/HTML embedding, kubeconfig context switcher in the header. Per-message Copy and Edit actions (hover any message); Suggestions picker right next to the input opens a searchable popover of the full template library.

• Templates — curated catalog of 159 prompt templates spanning all 27 tool categories. Sidebar filter by category, full-text search across title / prompt / tool name / tags. Click Use to drop a template into the chat input.

• Saved — bookmark your own reusable questions; one click sends them to chat.

• History — every past conversation, resumable.

• Audit — every MCP tool call ever executed (compliance trail).

• Settings — provider config, license registration, full tool inventory.

Compliance reporting (KubeCraft Pro)

KubeCraft Pro's generate_compliance_report tool produces audit-ready PDF and Word documents mapped to the major compliance frameworks. Run it from chat with one prompt like "Generate a SOC 2 compliance audit report and export PDF + Word".

Frameworks supported:

What the report contains:

1. Executive summary — color-coded status counts + a 0-100 compliance score with interpretation

2. Findings summary table — every control with status, control ID, and one-line summary

3. Detailed findings — per-control: status, evidence excerpt, cross-framework mappings, remediation guidance

4. Methodology — which tools were used to gather evidence, which findings need manual review

Evidence sources (run automatically, read-only):

inspect_rbac · summarize_pod_security_standards · analyze_network_reachability · find_unprotected_workloads · audit_secret_hygiene · summarize_image_vulnerabilities · scan_deprecations · audit_ingress_tls · audit_loadbalancers · get_node_health · list_pod_disruption_budgets

Multi-cluster: Set multi_cluster=true to loop over every kubeconfig context and produce one combined report — each finding is prefixed with the originating cluster name.

Output: Files are saved under KUBECRAFT_OUTPUT_DIR/compliance/ as kubecraft-compliance-{framework}-{timestamp}.{md,pdf,docx}. When the web UI is running, the chat response includes a Download link served by /api/v1/files/... (path-traversal protected, scoped to the output dir).

Note: This is an evidence-aggregation tool, not a substitute for a qualified auditor. Findings flagged 🔍 manual review require human verification (e.g., kube-apiserver flags, organizational controls outside the cluster).

Output beautification

Assistant replies and tool outputs are rendered with GitHub-flavored markdown, including:

• Mermaid diagrams — fenced ```mermaid blocks (returned by visualize_* tools) are rendered as interactive SVG with a toolbar: Copy source, Copy as PNG, Download PNG, Toggle source, Fullscreen. Mermaid is lazy-loaded so the bundle stays slim for users who never see a diagram.

• PNG renders — every render_* tool output (cluster topology, namespace, network, app architecture, premium architecture, GPU dashboard / metrics / sparkline) gets the same toolbar: Copy PNG, Download, Open in new tab, Fullscreen. Click the image to open it fullscreen; click the backdrop or press Esc to dismiss.

• 3D HTML topology (render_3d_topology, Pro) gets a matching panel: Open viewer (in-page iframe overlay), New tab (standalone Blob URL), Download (.html file), Copy (HTML source). Includes a size readout (e.g. "342 KB · self-contained Three.js HTML").

• Syntax-highlighted fenced code blocks (highlight.js, common-language bundle)

• Per-codeblock Copy button on hover

• JSON auto-pretty-print when fenced as ```json

• Wide tables with sticky headers + horizontal scroll wrapper

• Status emojis (✅ ❌ ⚠️ 🟢 🟡 🔴 ⏳) automatically rendered as tinted chips for fast scanning

Run web mode

Web mode has no authentication yet — bind it to localhost only (-p 127.0.0.1:8080:8080, or -e KUBECRAFT_HTTP_HOST=127.0.0.1 with --network=host); never publish it on a shared or public network.

Linux / WSL2 (recommended — uses host networking so the container can reach 127.0.0.1 clusters like kind/k3d/minikube):

docker run --rm --network=host \
  -v ~/.kube:/home/mcp/.kube:ro \
  -e KUBECONFIG=/home/mcp/.kube/config \
  -e KUBECRAFT_MODE=http \
  -e KUBECRAFT_HTTP_HOST=127.0.0.1 \
  -e KUBECRAFT_LLM_PROVIDER=anthropic \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  kubecraft-mcp:latest

Open http://localhost:8080.

Docker Desktop (Windows / macOS — --network=host is a no-op there; use host.docker.internal to reach a localhost cluster):

docker run --rm -p 127.0.0.1:8080:8080 --add-host=host.docker.internal:host-gateway \
  -v ~/.kube:/home/mcp/.kube:ro \
  -e KUBECONFIG=/home/mcp/.kube/config \
  -e KUBECRAFT_MODE=http \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  kubecraft-mcp:latest

Then rewrite your kubeconfig to use host.docker.internal instead of 127.0.0.1 for the cluster URL — see Troubleshooting below.

The same image still runs MCP stdio mode by default — KUBECRAFT_MODE=http (or --http) opts into the web UI.

Provider configuration

The Settings page shows whether the active provider is configured and lists every supported provider.

Tool surface limits per provider

The 73-tool Community build fits every provider's limit. With KubeCraft Pro installed, KubeCraft exposes 140 tools, but OpenAI and Azure OpenAI cap tools at 128 entries per request (Anthropic has no practical limit). KubeCraft handles this transparently with a smart tool selector (kubecraft_mcp/llm/tool_selector.py):

1. Anthropic — receives every tool, every turn. No filtering.

2. OpenAI / Azure OpenAI — receives a relevant subset of ≤128 tools per turn, chosen by:

   • Always-include core (~15 tools): cluster discovery, diagnostics, apply_manifest, etc.

   • Category routing: keyword classifier on your most recent prompt + last few user messages → matches against a tool/category map.

   • Priority padding: any remaining slots are filled by global priority order (most universally useful tools first).

You'll see the selected count in the server log on every turn (e.g. Tool subset for openai: 128/140 tools). If the LLM ever says it can't find a tool you expected, rephrase with stronger keywords ("audit my RBAC for risky bindings" rather than "check permissions") to surface the right category.

Develop the UI locally

The UI lives at ui/ inside this repo (not a separate project). For local dev:

# Terminal 1 — Python backend
KUBECRAFT_MODE=http ANTHROPIC_API_KEY=... python -m kubecraft_mcp

# Terminal 2 — Vite dev server (proxies /api/* to :8080)
cd ui && npm install && npm run dev
# → http://localhost:5173

For production builds, the Dockerfile bundles npm run build output into /app/ui/dist, served by FastAPI under /. No separate dev server needed.

Environment Variables

Project Structure

kubecraft-mcp-server/
├── Dockerfile
├── pyproject.toml
├── kubecraft_mcp/
│   ├── server.py              # MCP server entry point (73 Community tools)
│   ├── registry.py            # Tool registry (ToolSpec: schema + handler + tier + kind)
│   ├── plugins.py             # Entry-point plugin loader (how KubeCraft Pro adds its tools)
│   ├── licensing.py           # Edition seam: reports Community edition; KubeCraft Pro adds trials + license keys
│   ├── observability.py       # OpenTelemetry tracing + server stats
│   ├── k8s/
│   │   ├── client.py          # Kubernetes API client wrapper
│   │   ├── formatters.py      # Resource formatting utilities
│   │   ├── mermaid.py         # Mermaid diagram generation
│   │   ├── metrics_backend.py # Prometheus/Loki query backend
│   │   ├── renderer.py        # Shared colour palette for the Pillow renderers
│   │   ├── gpu_utils.py       # GPU extended-resource detection helpers
│   │   ├── gpu_renderer.py    # Pillow PNG dashboards for GPU allocation / metrics
│   │   └── logo_gen.py        # Programmatic KubeCraft logo generator
│   └── tools/
│       ├── cluster.py         # Cluster-level tools
│       ├── diagnostics.py     # Pod diagnostics and logs
│       ├── gateway_api.py     # Gateway API (HTTPRoute, GRPCRoute)
│       ├── gpu.py             # GPU workloads, readiness, Prometheus, nvidia-smi
│       ├── helm.py            # Helm releases + values (read-only)
│       ├── multicluster.py    # Multi-cluster context management
│       ├── openshift.py       # OpenShift-specific tools
│       ├── platform_posture.py # Storage, cert-manager, NetworkPolicy, endpoints
│       ├── policy_budgets.py  # PodDisruptionBudget listing
│       ├── policy_engines.py  # Kyverno / Gatekeeper policy summaries
│       ├── rbac_inspector.py  # RBAC role/binding inspection
│       ├── operators.py       # CRD & operator discovery (4 tools)
│       ├── network_advanced.py # IngressClasses, service mesh, CNI, CoreDNS, DNS lookup
│       ├── render.py          # PNG rendering (mermaid.ink + Pillow GPU dashboards) + auto-open
│       ├── resources.py       # Resource listing and describe
│       ├── storage_advanced.py # CSI drivers
│       ├── visualization.py   # Mermaid text diagram tools
│       ├── workloads.py       # DaemonSet, StatefulSet, CronJob/Job listing
│       ├── argocd.py          # ArgoCD detection + app/project listing (CRD-based)
│       ├── flux.py            # Flux CD integration (CRD-based)
│       └── tekton.py          # Tekton CI/CD integration (CRD-based)
├── kubecraft_mcp/llm/         # Multi-provider LLM bridge (web mode)
│   ├── base.py                # Provider ABC + streaming event types
│   ├── tool_bridge.py         # MCP tool → Anthropic/OpenAI tool_use translation
│   ├── anthropic_provider.py  # Claude (default) — drives the tool_use loop
│   ├── openai_provider.py     # OpenAI function calling
│   └── azure_provider.py      # Azure OpenAI (deployment-based)
├── kubecraft_mcp/web/         # FastAPI HTTP/SSE server bundled with the chat UI
│   ├── app.py                 # FastAPI factory + uvicorn entry point
│   ├── storage.py             # SQLite (sessions, messages, audit, saved)
│   ├── tool_runner.py         # Async wrapper that executes any registered MCP tool
│   ├── static.py              # Serves the built UI from /app/ui/dist
│   ├── templates_data.py      # Curated template library (159 prompts × 27 categories)
│   └── routes/
│       ├── chat.py            # POST /api/v1/ask (SSE streaming + tool orchestration)
│       ├── sessions.py        # Session CRUD
│       ├── config.py          # /api/v1/config (provider, instance metadata)
│       ├── audit.py           # /api/v1/audit (tool invocation log)
│       ├── saved.py           # Saved questions + suggested-questions starter prompts
│       ├── templates.py       # /api/v1/templates (curated library)
│       ├── files.py           # /api/v1/files (download exported reports / artifacts)
│       └── kubecraft.py       # /api/v1/contexts, /api/v1/license, /api/v1/tools
├── kubecraft_mcp/__main__.py  # Dispatcher: stdio (default) | http (KUBECRAFT_MODE=http)
├── ui/                        # React/TypeScript chat UI (Vite + Tailwind + Zustand)
│   ├── src/
│   │   ├── App.tsx            # Routes: /chat, /templates, /saved, /history, /audit, /settings
│   │   ├── pages/             # ChatPage, TemplatesPage, SavedPage, HistoryPage, AuditPage, SettingsPage
│   │   ├── components/        # Header, MessageCard, MarkdownView (highlight.js), ToolInvocationCard, SuggestionsPicker, ContextPicker, CopyButton
│   │   ├── store/chat.ts      # Zustand chat store with streaming reducers
│   │   └── lib/{api,stream,format,copy,icons}.ts(x)
│   ├── package.json
│   ├── vite.config.ts         # Proxies /api/* → :8080 in dev
│   └── tailwind.config.js     # KubeCraft brand palette
└── .cursor/
    └── mcp.json               # Cursor MCP configuration

Troubleshooting

Windows: "Permission denied" on /output (diagrams not saved)

If you see warnings like Permission denied: '/output/index.html' in the MCP server logs, diagrams still work inline but the optional file-save to your host directory fails. This is a Docker Desktop volume-mount permissions issue.

Fix: Ensure the host directory exists before starting the container:

mkdir C:\Users\<user>\kubecraft-diagrams

Then confirm your config maps it correctly:

"-v", "C:\\Users\\<user>\\kubecraft-diagrams:/output"

If the error persists, check that Docker Desktop has file-sharing access to the drive (Settings → Resources → File sharing). Alternatively, use a named Docker volume:

"-v", "kubecraft-output:/output"

Note: Diagrams are always returned inline via MCP regardless of whether the file-save succeeds. The file-save is a convenience for hosts like Claude Desktop that don't render MCP images natively.

Diagrams don't auto-open in browser

Auto-open uses webbrowser.open() which requires the container to reach the host display. Inside Docker, this only works with X11 forwarding or host networking on Linux. On Windows/macOS Docker Desktop, open the saved files from your host-mounted KUBECRAFT_OUTPUT_DIR directory instead, or use the dashboard at <KUBECRAFT_OUTPUT_DIR>/index.html (auto-refreshes every 5 seconds).

Kubernetes API server unreachable (connection refused)

If tools fail with errors like:

HTTPSConnectionPool(host='127.0.0.1', port=53842): Max retries exceeded ...
[Errno 111] Connection refused

…the cause is that your kubeconfig points to a localhost endpoint on the host (typical for kind, k3d, minikube, or kubectl proxy), but inside the container 127.0.0.1 is the container's own loopback — which has nothing listening.

Diagnose first:

kubectl config view --minify -o jsonpath='{.clusters[0].cluster.server}'
# → e.g. https://127.0.0.1:53842   ← that's the smoking gun

Fix on Linux / WSL2 — use host networking:

docker run --rm --network=host -e KUBECRAFT_MODE=http -e KUBECRAFT_HTTP_HOST=127.0.0.1 ... kubecraft-mcp:latest

--network=host shares the container's network namespace with the host so 127.0.0.1:53842 resolves correctly. Note: with --network=host you don't need -p 127.0.0.1:8080:8080 (and Docker will reject combining the two).

Fix on Docker Desktop (Windows / macOS) — --network=host is a no-op:

⚠️ TLS gotcha: kind/k3d/minikube apiserver certificates have SANs only for 127.0.0.1, localhost, and kubernetes. After rewriting the URL to host.docker.internal, Python rejects the cert with SSL: CERTIFICATE_VERIFY_FAILED — Hostname mismatch. You must therefore also disable TLS verification in the container-only kubeconfig copy. This is acceptable for local dev because these certs are self-signed anyway — but never do it for production clusters.

1. Add the host-gateway alias when you docker run:

   docker run --rm -p 127.0.0.1:8080:8080 --add-host=host.docker.internal:host-gateway ...

2. Make a container-only kubeconfig copy that rewrites the URL and turns off TLS verification:

   # On the host:
   sed -e 's|https://127\.0\.0\.1:|https://host.docker.internal:|' \
       -e '/certificate-authority-data:/d' \
       ~/.kube/config > ~/.kube/config.docker
   sed -i 's|^\(\s*\)server: https://host.docker.internal|\1insecure-skip-tls-verify: true\n\1server: https://host.docker.internal|' \
       ~/.kube/config.docker

3. Mount the rewritten file:

   docker run --rm -p 127.0.0.1:8080:8080 --add-host=host.docker.internal:host-gateway \
     -v ~/.kube/config.docker:/home/mcp/.kube/config:ro \
     -e KUBECRAFT_MODE=http -e ANTHROPIC_API_KEY=... \
     kubecraft-mcp:latest

💡 WSL2 users: skip this section. WSL2's Docker engine supports --network=host natively — use the Linux fix above. You keep proper TLS verification and your kubeconfig stays untouched.

Fix for remote clusters (EKS / AKS / GKE / OpenShift):

These already have routable hostnames, so this issue only affects local clusters. If you see it against a remote cluster, check whether your kubeconfig has been overridden by a kubectl proxy session.

Requirements

• Docker

• A kubeconfig with access to your target cluster

• Cursor, Claude Desktop, Claude Code, or any MCP-compatible AI assistant

License

The KubeCraft MCP Server Community Edition in this repository is open source under the MIT License — all 73 Community tools, no trial, no license key.

KubeCraft Pro is a separately licensed add-on from CloudCraft Labs that registers 67 additional tools (140 total). Pro includes a 30-day trial and commercial license keys; see cloudcraftlabs.io for details.

• In the Community build, get_license_info reports the Community edition and register_license explains that registration applies to KubeCraft Pro

• With Pro installed, the same two tools manage the Pro trial and license