k8s-lens-mcp 0.1.0

A Model Context Protocol (MCP) server for intelligent Kubernetes natural language interaction.

🔭 K8s Lens MCP

A Model Context Protocol (MCP) server for intelligent, natural-language-powered Kubernetes operations.

Stop memorizing kubectl flags. Ask your cluster questions in plain English.

---

✨ What It Does

K8s Lens MCP exposes deep analytical tools to any MCP-compatible AI assistant (Claude, Cursor, Copilot, etc.):

Capability	Example Prompt
Smart Resource Queries	"Show me all pods with status CrashLoopBackOff in namespace staging"
Pod Root-Cause Analysis	"Why is this pod failing?" — correlates events, logs, resource limits, and node conditions
Cross-Environment Diff	"Diff the nginx deployment between staging and prod"
Manifest Generation	"Create a basic nginx deployment with 2 replicas and a LoadBalancer service"

Unlike thin kubectl wrappers, K8s Lens MCP analyzes and correlates data so the AI can give you real answers, not just raw command output.

---

🚀 Quick Start

1. Install

pip install k8s-lens-mcp

Or with Poetry:

poetry add k8s-lens-mcp

2. Configure Your AI Client

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "k8s-lens": {
      "command": "k8s-lens-mcp",
      "args": ["--context", "my-cluster", "--namespace", "default"]
    }
  }
}

Cursor

Add to Cursor Settings → MCP:

{
  "mcpServers": {
    "k8s-lens": {
      "command": "k8s-lens-mcp",
      "args": ["--namespace", "production"]
    }
  }
}

SSE Transport (for remote or containerized setups)

If you run the server in a container or on a remote host, use SSE transport:

k8s-lens-mcp --transport sse --port 8000

Then point your MCP client at http://localhost:8000/sse.

3. Start Talking to Your Cluster

Open Claude or Cursor and ask:

"Show me all failing pods in the default namespace and tell me why they're failing."

---

🐳 Docker

Build

docker build -t k8s-lens-mcp:latest .

Run (stdio — default)

docker run --rm -it \
  -v ~/.kube:/home/k8slens/.kube:ro \
  k8s-lens-mcp:latest

Run (SSE — HTTP mode)

docker run --rm -p 8000:8000 \
  -v ~/.kube:/home/k8slens/.kube:ro \
  k8s-lens-mcp:latest \
  --transport sse --port 8000

Docker Compose

docker compose up

The SSE endpoint will be available at http://localhost:8000/sse.

---

🛡️ Safety First

• Read-only by default — the server starts in --read-only mode. No accidental deletions.
• RBAC-respecting — we use your kubeconfig / ServiceAccount. We don't bypass Kubernetes permissions.
• Secret masking — Kubernetes Secret data is never returned in tool output.

To enable read-write mode (future feature):

k8s-lens-mcp --read-only=false

---

🛠️ Tools Reference

get_resources

Query Kubernetes resources with flexible filters.

Example prompts:

• "Show me all pods with status CrashLoopBackOff in namespace staging"
• "List all deployments in the default namespace"
• "Get nodes with label zone=us-east-1"

Parameters: resource_type, namespace, labels, status, field_selector, limit

analyze_pod

Deep root-cause analysis for a failing or misbehaving pod.

Example prompts:

• "Why is my-pod failing?"
• "Why does api-7d9f4b2c keep restarting?"
• "Diagnose pod web-0 in namespace production"

Parameters: pod_name, namespace, container, tail_lines

compare_deployments

Diff two Kubernetes resources across namespaces or clusters.

Example prompts:

• "Diff the nginx deployment between staging and prod"
• "Compare the api deployment in dev vs production"

Parameters: resource_kind, name, namespace_a, namespace_b, context_a, context_b

generate_manifest

Generate best-practice Kubernetes YAML manifests from natural language.

Example prompts:

• "Create a basic nginx deployment with 2 replicas and a LoadBalancer service"
• "Generate a Redis deployment with a ClusterIP service on port 6379"

Parameters: description, kind, namespace

---

🏗️ Development

Prerequisites

• Python 3.11+
• Poetry
• A Kubernetes cluster (e.g. kind, minikube, or a remote cluster)

Setup

git clone https://github.com/yourusername/k8s-lens-mcp.git
cd k8s-lens-mcp
poetry install

Run Locally

poetry run k8s-lens-mcp

Test with MCP Inspector

npx @modelcontextprotocol/inspector poetry run k8s-lens-mcp

Run Tests

poetry run pytest

Lint & Format

poetry run ruff check .
poetry run ruff format .

---

📋 Roadmap

• Core MCP server scaffold
• get_resources — filtered resource queries
• analyze_pod — multi-signal root cause analysis
• compare_deployments — cross-environment diffing
• generate_manifest — best-practice manifest generation
• Cost / resource optimization advisor
• Multi-cluster context aggregation
• Helm release values diffing
• In-cluster deployment (Helm chart)
• kubectl plugin wrapper (kubectl lens "...")

---

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Please read our Code of Conduct.

---

📄 License

MIT