Dev/Infra

from remiphilippe

MCP server that gives LLMs full control over local Kubernetes dev environments via k3d, kubectl, Tilt, Helm, and kustomize

🔥🔥🔥🔥✓ VerifiedFreeQuick setup

#automation #scraping #devops #git #monitoring #memory

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

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)

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