KubeCraft Server

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

Features (140 tools)

Category	Tools	Count
Cluster Info	get_cluster_info, list_namespaces, list_nodes (includes GPU(alloc) column), get_node_health	4
Resources	list_pods, list_deployments, list_services, list_ingresses, list_gateway_api, list_hpas, list_resource_quotas, list_pod_disruption_budgets, list_resources, describe_resource, get_resource_usage	11
Diagnostics	diagnose_pod, get_pod_logs, get_events	3
Management	scale_deployment, restart_deployment, rollout_history, rollback_deployment, cordon_node, uncordon_node, delete_resource, apply_manifest, validate_manifest	9
Platform / Posture	inspect_rbac, list_storage_overview, cert_manager_health, summarize_network_policies, diagnose_service_endpoints, summarize_policy_engines	6
Security Posture	summarize_pod_security_standards, audit_service_accounts, summarize_image_vulnerabilities, audit_secret_hygiene	4
Workloads	list_daemonsets, restart_daemonset, list_statefulsets, scale_statefulset, restart_statefulset, list_cronjobs, list_jobs, trigger_cronjob, analyze_pod_disruption	9
Cluster Intelligence	cluster_health_score, scan_deprecations, unused_resource_report	3
Advanced Storage	list_csi_drivers (capabilities + node registration), list_volume_snapshots (snapshot.storage.k8s.io), analyze_storage_capacity (PV/PVC utilization + CSIStorageCapacity)	3
Advanced Networking	list_ingress_classes, detect_service_mesh (Istio/Linkerd/Cilium + sidecar status), detect_cni (Calico/Cilium/Flannel/AWS VPC/etc.), diagnose_coredns, analyze_network_reachability (NetworkPolicy posture), visualize_network_policies (Mermaid graph), simulate_pod_reachability (pure-logic NetworkPolicy walker), visualize_egress_allowances (NS → external CIDR Mermaid), find_unprotected_workloads (zero-trust gap detector), audit_loadbalancers (LB services + pending allocations), port_conflict_check (NodePort + hostNetwork conflicts), dns_lookup (cluster-DNS view of any hostname)	12
Ingress Audit	audit_ingress_endpoints (backends + TLS), audit_ingress_tls (cert expiry, sorted by urgency), visualize_ingress_topology (Mermaid Ingress → Service → Pod chains), test_ingress_connectivity (synthetic curl probe with timing breakdown)	4
Access Control (RBAC YAML)	grant_namespace_access (viewer/editor/admin), grant_resource_access (least-privilege Role generator + lint warnings), revoke_access (find + remove all bindings)	3
Compliance Reporting	generate_compliance_report — aggregates evidence from 11 audit-relevant tools and exports to Markdown + PDF + DOCX. Supports CIS Kubernetes Benchmark, SOC 2, ISO 27001, NIST 800-53, PCI-DSS, HIPAA, or comprehensive (all). Multi-cluster optional.	1
CRDs & Operators	list_crds, describe_crd, count_custom_resources (find bloat), detect_operators (combines OLM + known-group + Deployment-pattern signals), audit_finalizers (stuck-Terminating resources + unstuck recipes), audit_operator_rbac (flag operators running with cluster-admin), find_orphan_crs (CRs after operator uninstall), audit_crd_versions (multi-version + conversion strategy + preserveUnknownFields), list_olm_subscriptions, visualize_operators (Mermaid: operators → CRDs → CR counts)	10
Visualization	visualize_cluster_topology, visualize_namespace, visualize_network, visualize_app_architecture, analyze_connections	5
Rendered Diagrams	render_cluster_topology, render_namespace, render_network, render_app_architecture, render_app_architecture_premium, render_gpu_dashboard, render_gpu_metrics, render_gpu_sparkline	8
3D Visualization	render_3d_topology — interactive Three.js 3D cluster topology returned as MCP EmbeddedResource (HTML) + auto-opens in browser	1
Multi-Cluster	list_contexts, switch_context, multi_cluster_overview	3
Pod Exec	exec_command	1
Helm	helm_list, helm_get_values, helm_install, helm_uninstall	4
Cost Analysis	analyze_cost, rightsizing_report	2
OpenShift	openshift_detect, openshift_list_routes, openshift_list_projects, openshift_list_builds	4
ArgoCD	argocd_detect, argocd_list_apps, argocd_get_app, argocd_list_projects, argocd_app_history, argocd_sync_app, argocd_rollback_app, visualize_argocd	8
Flux CD	flux_detect, flux_list_sources, flux_list_kustomizations, flux_list_helmreleases, visualize_flux	5
Tekton	tekton_detect, tekton_list_pipelines, tekton_list_runs, tekton_list_tasks, visualize_tekton	5
GitOps Overview	visualize_gitops — unified Mermaid diagram of all detected CD tools	1
GPU / Accelerators	list_gpu_workloads, gpu_cluster_readiness, visualize_gpu_allocation, visualize_gpu_metrics, gpu_nvidia_smi, get_gpu_promql_reference	6
Observability	get_server_stats (OpenTelemetry), prometheus_query, loki_query	3
License	get_license_info, register_license	2

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

Diagram & Visual Rendering

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

Content	MCP response type	Inline rendering	Fallback
PNG diagrams (render_*)	ImageContent (base64 PNG)	Cursor renders inline	Auto-opens saved PNG in default viewer; also saved to KUBECRAFT_OUTPUT_DIR
3D topology (render_3d_topology)	EmbeddedResource (base64 HTML, text/html)	Future clients that support EmbeddedResource	Auto-opens HTML in default browser; also saved to KUBECRAFT_OUTPUT_DIR or temp dir
Mermaid text (visualize_*)	TextContent (markdown)	Cursor + Claude Desktop render natively	Copy Mermaid block to any Mermaid renderer

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.

Distribution	Status	Notes
Vanilla K8s / KinD	Fully supported	Primary dev/test target
Amazon EKS	Fully supported	kubeconfig via aws eks update-kubeconfig
Azure AKS	Fully supported	kubeconfig via az aks get-credentials
Google GKE	Fully supported	kubeconfig via gcloud container clusters get-credentials
Canonical K8s / MicroK8s	Fully supported	CNCF certified, standard APIs
k3s / Rancher	Fully supported	Lightweight but fully conformant
Red Hat OpenShift	Fully supported	Standard K8s tools + OCP-specific tools for Routes, Projects, BuildConfigs

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): 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 entire 115-tool surface 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 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'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:

Framework	Mapping
CIS Kubernetes Benchmark v1.9	Direct control-ID mapping (5.1.x RBAC, 5.2.x PSS, 5.3.x networking, 5.4.x secrets, etc.)
SOC 2 Trust Service Criteria	CC6.x logical access · CC7.x system operations · CC8.x change management
ISO 27001:2022	Annex A (A.5 access control · A.8 operations / cryptography / network security)
NIST 800-53 Rev. 5	AC, AU, CM, IA, RA, SC, SI control families
PCI-DSS v4.0	Req 1, 2, 6, 7, 8, 10
HIPAA Security Rule	§164.312 Technical Safeguards (a) Access · (b) Audit · (c) Integrity · (e) Transmission
comprehensive	All of the above in one report — every finding lists its mapping in each framework

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

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_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 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

Provider	Env vars
Anthropic Claude (default)	KUBECRAFT_LLM_PROVIDER=anthropic · ANTHROPIC_API_KEY · optional KUBECRAFT_LLM_MODEL (default claude-sonnet-4-6; other options: claude-opus-4-7, claude-haiku-4-5-20251001)
OpenAI	KUBECRAFT_LLM_PROVIDER=openai · OPENAI_API_KEY · optional KUBECRAFT_LLM_MODEL (default gpt-4o)
Azure OpenAI	KUBECRAFT_LLM_PROVIDER=azure-openai · AZURE_OPENAI_KEY · AZURE_OPENAI_ENDPOINT · AZURE_OPENAI_DEPLOYMENT · optional AZURE_OPENAI_API_VERSION

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

Tool surface limits per provider

KubeCraft exposes 130+ 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/130 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

Variable	Description
KUBECONFIG	Path to kubeconfig file
KUBECRAFT_OUTPUT_DIR	Directory for saving diagrams and 3D HTML files. Saved files are auto-opened in the default browser/viewer. Pre-created as /output inside the container image
KUBECRAFT_VIEWER_BIND	Optional bind for built-in 3D viewer URL. Loopback: 127.0.0.1:0, localhost:0, ::1:0. With KUBECRAFT_VIEWER_EXPOSE=1, also 0.0.0.0:PORT (for docker run -p host:port)
KUBECRAFT_VIEWER_EXPOSE	Set to 1 to allow binding 0.0.0.0 so Docker port publishing works. The viewer still uses unguessable URLs; avoid on hostile networks without firewall rules
KUBECRAFT_CPU_HOUR_RATE	Cost analysis CPU rate (default: $0.031/vCPU-hr)
KUBECRAFT_MEM_GIB_HOUR_RATE	Cost analysis memory rate (default: $0.004/GiB-hr)
OTEL_EXPORTER_OTLP_ENDPOINT	OpenTelemetry OTLP endpoint for trace export
ARGOCD_SERVER	ArgoCD server URL for sync/rollback actions (e.g. https://argocd.example.com)
ARGOCD_TOKEN	ArgoCD API token for authenticated REST operations
KUBECRAFT_PROMETHEUS_URL	Prometheus base URL for prometheus_query, visualize_gpu_metrics, render_gpu_metrics, render_gpu_sparkline (e.g. https://prometheus.example.com)
KUBECRAFT_PROMETHEUS_TOKEN	Optional Bearer token for Prometheus
KUBECRAFT_PROMETHEUS_USER / KUBECRAFT_PROMETHEUS_PASSWORD	Optional basic auth for Prometheus (used instead of token when both are set)
KUBECRAFT_LOKI_URL	Loki base URL for loki_query (e.g. https://loki.example.com)
KUBECRAFT_LOKI_TOKEN	Optional Bearer token for Loki
KUBECRAFT_LOKI_USER / KUBECRAFT_LOKI_PASSWORD	Optional basic auth for Loki
KUBECRAFT_LOKI_ORG_ID	Optional X-Scope-OrgID header for multi-tenant Loki
KUBECRAFT_LICENSE_KEY	License key (overrides file-based license)
KUBECRAFT_EMAIL	Email address for license registration
KUBECRAFT_MODE	stdio (default — MCP) or http (web UI on port 8080). Equivalent to passing --http
KUBECRAFT_HTTP_HOST	Bind address for web mode (default 0.0.0.0)
KUBECRAFT_HTTP_PORT	Port for web mode (default 8080)
KUBECRAFT_INSTANCE_NAME	Optional label shown in the UI header to distinguish multiple deployments
KUBECRAFT_LLM_PROVIDER	anthropic (default), openai, or azure-openai
KUBECRAFT_LLM_MODEL	Override the default model for the active provider
ANTHROPIC_API_KEY	API key for Anthropic Claude provider
ANTHROPIC_BASE_URL	Optional Anthropic API base URL (proxies, mirrors)
OPENAI_API_KEY	API key for OpenAI provider
OPENAI_BASE_URL	Optional OpenAI base URL (compatible endpoints, proxies)
AZURE_OPENAI_KEY / AZURE_OPENAI_ENDPOINT / AZURE_OPENAI_DEPLOYMENT / AZURE_OPENAI_API_VERSION	Azure OpenAI configuration (deployment-based; KUBECRAFT_LLM_MODEL falls back to the deployment name)
KUBECRAFT_CORS_ORIGINS	Comma-separated CORS allow-list for web mode (default http://localhost:5173 for Vite dev). Production same-origin deploys can ignore

Project Structure

kubecraft-mcp-server/
├── Dockerfile
├── pyproject.toml
├── kubecraft_mcp/
│   ├── server.py              # MCP server entry point (140 tools)
│   ├── licensing.py           # 30-day trial + commercial license management
│   ├── 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        # Pillow-based PNG dashboard renderer
│   │   ├── topology_3d.py     # Three.js 3D topology viewer + auto-open
│   │   ├── 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
│       ├── cleanup.py         # Unused resource cleanup report
│       ├── cost.py            # Cost analysis and rightsizing
│       ├── deprecation.py     # API deprecation scanner
│       ├── diagnostics.py     # Pod diagnostics and logs
│       ├── exec.py            # Pod exec (command execution)
│       ├── gateway_api.py     # Gateway API (HTTPRoute, GRPCRoute)
│       ├── gpu.py             # GPU workloads, readiness, Prometheus, nvidia-smi
│       ├── health.py          # Composite cluster health score
│       ├── helm.py            # Helm integration
│       ├── management.py      # Scale, restart, cordon, apply
│       ├── 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
│       ├── access_control.py  # RBAC YAML generators: grant_namespace_access, grant_resource_access, revoke_access
│       ├── compliance.py      # Compliance audit report generator (CIS/SOC2/ISO27001/NIST/PCI/HIPAA → Markdown/PDF/DOCX)
│       ├── operators.py       # CRD & operator essentials (10 tools)
│       ├── ingress_audit.py   # Per-Ingress endpoint health + TLS cert decoding
│       ├── network_advanced.py # IngressClasses, service mesh, CNI, CoreDNS, reachability + Mermaid graph + pod reachability simulator
│       ├── render.py          # Image rendering (PNG + 3D HTML + auto-open)
│       ├── resources.py       # Resource listing and describe
│       ├── security_posture.py # PSS, SA audit, image vulns, secret hygiene
│       ├── storage_advanced.py # CSI drivers, VolumeSnapshots, storage capacity
│       ├── visualization.py   # Mermaid text diagram tools
│       ├── wave3_observability.py # Prometheus and Loki query tools
│       ├── workloads.py       # DaemonSet, StatefulSet, CronJob/Job, disruption
│       ├── argocd.py          # ArgoCD integration (CRD + REST API)
│       ├── 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 ... 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 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 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 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

KubeCraft MCP Server is a commercial product by CloudCraft Labs.

• 30-day free trial — no credit card required
• $200/year after trial — one license, unlimited clusters
• Use get_license_info and register_license tools to manage your license