🔭 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-onlymode. 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
CrashLoopBackOffin namespacestaging" - "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-podfailing?" - "Why does
api-7d9f4b2ckeep restarting?" - "Diagnose pod
web-0in namespaceproduction"
Parameters: pod_name, namespace, container, tail_lines
compare_deployments
Diff two Kubernetes resources across namespaces or clusters.
Example prompts:
- "Diff the nginx deployment between
stagingandprod" - "Compare the
apideployment indevvsproduction"
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)
-
kubectlplugin wrapper (kubectl lens "...")
🤝 Contributing
We welcome contributions! See CONTRIBUTING.md for guidelines.
Please read our Code of Conduct.
📄 License
Metadata
Release files for k8s-lens-mcp 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| k8s_lens_mcp-0.1.0.tar.gz | 27.1 kB | Without provenance | Details for k8s_lens_mcp-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| k8s_lens_mcp-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for k8s_lens_mcp-0.1.0-py3-none-any.whl |
Total release size: 58.1 kB
Release files / k8s_lens_mcp-0.1.0.tar.gz
| Download URL | k8s_lens_mcp-0.1.0.tar.gz |
|---|---|
| Size | 27.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
126a7db2ac3bf34c72fe9c937a9975ab413c86a680076b84141f92096a6a13ef
|
|
BLAKE2b-256 checksum How to use checksums |
577bbfda9b596c1e07c95c7df67b3270dc3d56b16f97fd93a3231ae33c6a3eb6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.4.1 CPython/3.14.5 Darwin/25.4.0
|
Release files / k8s_lens_mcp-0.1.0-py3-none-any.whl
| Download URL | k8s_lens_mcp-0.1.0-py3-none-any.whl |
|---|---|
| Size | 31.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c91a9290cb21ec5eabdd8bad54bc2f085ebc0c7c643e1ce9f2874531a039009e
|
|
BLAKE2b-256 checksum How to use checksums |
6619ae995b3f64fd8dab7e2aa4182b4fe5e57d6b252dae6a85caf04f69184761
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.4.1 CPython/3.14.5 Darwin/25.4.0
|
Security for k8s-lens-mcp 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.