devinfra-mcp

MCP server that gives LLMs full control over local Kubernetes dev environments. Built in Go, it exposes 63 tools across 8 groups for managing k3d clusters, kubectl operations, Helm charts, Kustomize overlays, Tilt dev workflows, Artifact Hub lookups, and documentation search.

Features

• k3d (9 tools) — create, delete, start, stop, list clusters and nodes
• kubectl (16 tools) — get, describe, apply, delete, logs, port-forward, raw command escape hatch
• Helm (10 tools) — install, upgrade, uninstall, template, status, show values/chart, repo management (via Go SDK)
• Kustomize (5 tools) — build, build-and-apply, edit image/namespace, list resources (via Go API)
• Tilt (10 tools) — up, down, ci, logs, status, get, describe, trigger, session (queries via HTTP API)
• Artifact Hub (6 tools) — search, package info, values, schema, readme, templates
• Doc search (4 tools) — full-text search over tilt, k3d, kubectl, and Helm docs (Bleve index, 257+ pages)
• CI (3 tools) — composite bootstrap, teardown, and diagnostic collection

Architecture

Hybrid approach — each tool group uses the best integration method:

Component	Integration	Why
Helm	Go SDK (helm.sh/helm/v3)	Type safety, no CLI dependency
Kustomize	Go API (sigs.k8s.io/kustomize/api)	Designed for embedding
Tilt queries	HTTP API (auto-discovered apiserver)	Structured JSON, no process spawn
Tilt lifecycle	CLI shell-out	CLI-first, no public Go SDK
kubectl	CLI shell-out	Avoids client-go bloat, inherits user auth
k3d	CLI shell-out	No public Go API

Prerequisites

• Go 1.26+
• Docker (for k3d clusters)
• k3d — local Kubernetes clusters
• kubectl — cluster interaction
• tilt — dev workflow orchestration
• Helm and Kustomize are optional at the CLI level (Go SDKs are embedded)

Quick Start

# Build the binary
make build

# Run over stdio (default MCP transport)
./bin/devinfra-mcp

# Run as HTTP server
./bin/devinfra-mcp --http --addr :8080

# With a config file
./bin/devinfra-mcp --config settings.json

MCP Client Configuration

Claude Code / Claude Desktop

Add to .mcp.json in your project root (or ~/.claude.json for global):

{
  "mcpServers": {
    "devinfra-mcp": {
      "command": "devinfra-mcp",
      "args": ["--config", "/path/to/settings.json"]
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root (or ~/.cursor/mcp.json for global):

{
  "mcpServers": {
    "devinfra-mcp": {
      "command": "devinfra-mcp",
      "args": ["--config", "/path/to/settings.json"]
    }
  }
}

OpenAI Codex

Add to .codex/config.toml in your project root (or ~/.codex/config.toml for global):

[mcp_servers.devinfra-mcp]
command = "devinfra-mcp"
args = ["--config", "/path/to/settings.json"]

Streamable HTTP (any client)

Instead of stdio, you can run the server over HTTP for clients that support remote MCP servers:

./bin/devinfra-mcp --http --addr :8080 --config settings.json

Configuration

Create a JSON config file to override defaults. The config must be valid JSON — no comments are allowed.

{
  "kubeconfig": "",
  "default_context": "",
  "blocked_contexts": ["production", "staging-*"],
  "tilt_api": "",
  "kubectl_apply_dry_run_default": "client",
  "doc_index_path": "~/.devinfra-mcp/docs.bleve",
  "doc_sources": {
    "tilt": "github.com/tilt-dev/tilt.build/docs",
    "k3d": "github.com/k3d-io/k3d/docs",
    "k8s": "embedded"
  },
  "timeouts": {
    "default": "30s",
    "logs": "10s",
    "apply": "60s",
    "cluster_create": "120s",
    "tilt_ci": "300s"
  },
  "artifacthub": {
    "enabled": true,
    "base_url": "https://artifacthub.io/api/v1",
    "cache_ttl": "1h",
    "prefer_verified_publisher": true,
    "auto_lookup_on_install": true,
    "timeout": "10s"
  }
}

Field	Description
kubeconfig	Path to kubeconfig (empty = default ~/.kube/config)
default_context	Override kubeconfig current-context
blocked_contexts	Glob patterns for contexts the safety layer will reject
tilt_api	Tilt apiserver URL (empty = auto-discover from ~/.tilt-dev/config)
kubectl_apply_dry_run_default	Default dry-run mode for kubectl_apply (client, server, or none)
doc_index_path	Path to the Bleve search index (supports ~/)
artifacthub.enabled	Feature gate for Artifact Hub tools
artifacthub.auto_lookup_on_install	Auto-fetch values before helm_install/helm_upgrade

Safety

• kubectl_apply defaults to dry_run: "client" — real apply requires explicit dry_run: "none"
• Blocked contexts (e.g., production, staging-*) reject operations at the safety layer
• kubectl_raw validates args against a denylist; override requires unsafe: true
• kubectl_logs --follow is capped at 10 seconds

Documentation Search

The server includes an embedded Bleve full-text search index over 4 documentation sources:

Source	Docs	Repository
tilt	~54	tilt-dev/tilt.build
k3d	~33	k3d-io/k3d
k8s	~75	kubernetes/website (kubectl reference)
helm	~95	helm/helm-www

# Clone doc sources (uses sparse checkout for large repos)
make docs-clone

# Build the Bleve search index
make docs-index

Development

make build              # Build binary to bin/devinfra-mcp
make test               # Unit tests
make test-integration   # Integration tests (needs Docker)
make e2e                # Full e2e: create k3d cluster, test, teardown
make lint               # golangci-lint
make vet                # go vet
make check              # vet + lint + test

Prompts

Reusable workflow templates the LLM can invoke for multi-step operations:

Prompt	Description	Arguments
bootstrap_dev_env	Create k3d cluster, merge kubeconfig, apply kustomize, start tilt	cluster_name, kustomize_path, tiltfile_path
teardown_dev_env	Stop tilt and delete k3d cluster	cluster_name
debug_pod	Describe, logs, and events for a failing pod	pod_name, namespace
deploy_and_verify	Kustomize build + apply, rollout status, verify pods	kustomize_path, namespace, deployment_name
cluster_health_check	Cluster info, node status, resource usage, warning events	—
ci_run	Bootstrap CI cluster, run tilt ci, diagnostics on failure, teardown	cluster_name, tiltfile_path
search_and_apply	Search docs for a concept and show relevant patterns	topic
helm_deploy_and_verify	Artifact Hub lookup, helm install, rollout status, verify	chart, release, namespace

Resources

Read-only data the LLM can pull into context:

Resource URI	Description
k8s://cluster/{name}/info	Cluster info (nodes, version, endpoint)
k8s://cluster/{name}/namespaces	List of namespaces
k8s://namespace/{ns}/pods	Pods (JSON)
k8s://namespace/{ns}/services	Services (JSON)
k8s://namespace/{ns}/deployments	Deployments (JSON)
k8s://namespace/{ns}/events	Recent events (JSON)
k8s://tilt/status	Tilt resource status (if running)
k8s://tilt/session	Tilt Session object for CI monitoring
k8s://kubeconfig	Current kubeconfig (minified)
k8s://helm/releases	Helm releases in current context
docs://{source}/{slug}	Doc page (source: tilt, k3d, k8s, helm)

Project Structure

cmd/devinfra-mcp/main.go           Entry point, wires all components
internal/
  executor/                        Shell-out abstraction (all CLI calls go through here)
  tools/                           63 MCP tools across 8 groups
    k3d.go, kubectl.go, helm.go,
    kustomize.go, tilt.go,
    artifacthub.go, docsearch.go, ci.go
  helmclient/                      Helm Go SDK wrapper (Client interface + mock)
  kustomizeclient/                 Kustomize Go API wrapper (Client interface + mock)
  tilt/                            Tilt HTTP API client (Client interface + mock)
  artifacthub/                     Artifact Hub HTTP client with response caching
  docsearch/                       Bleve index builder + markdown scraper
  config/                          JSON config loading with defaults
  safety/                          Context blocklist, input sanitization
  prompts/                         MCP prompt templates
  resources/                       MCP resource providers (cluster state, docs)

License

See LICENSE for details.