Metadata-Version: 2.4
Name: k8s-lens-mcp
Version: 0.1.0
Summary: A Model Context Protocol (MCP) server for intelligent Kubernetes natural language interaction.
License: MIT
License-File: LICENSE
Keywords: kubernetes,mcp,llm,ai,devops,kubectl
Author: Firas Mosbehi
Author-email: firas.mosbehi@insat.ucar.tn
Requires-Python: >=3.11,<4.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Requires-Dist: deepdiff (>=8.4.0,<9.0.0)
Requires-Dist: kubernetes (>=32.0.0,<33.0.0)
Requires-Dist: mcp (>=1.6.0,<2.0.0)
Requires-Dist: opentelemetry-api (>=1.29.0,<2.0.0)
Requires-Dist: opentelemetry-instrumentation (>=0.50b0,<0.51)
Requires-Dist: opentelemetry-sdk (>=1.29.0,<2.0.0)
Requires-Dist: pydantic (>=2.10.0,<3.0.0)
Requires-Dist: pyyaml (>=6.0.2,<7.0.0)
Project-URL: Homepage, https://github.com/firas-mcp-servers/k8s-lens-mcp
Project-URL: Repository, https://github.com/firas-mcp-servers/k8s-lens-mcp
Description-Content-Type: text/markdown

# 🔭 K8s Lens MCP

<!-- mcp-name: io.github.firas-mcp-servers/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

```bash
pip install k8s-lens-mcp
```

Or with Poetry:

```bash
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):

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

#### Cursor

Add to Cursor Settings → MCP:

```json
{
  "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:

```bash
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

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

### Run (stdio — default)

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

### Run (SSE — HTTP mode)

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

### Docker Compose

```bash
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):

```bash
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](https://kind.sigs.k8s.io/), minikube, or a remote cluster)

### Setup

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

### Run Locally

```bash
poetry run k8s-lens-mcp
```

### Test with MCP Inspector

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

### Run Tests

```bash
poetry run pytest
```

### Lint & Format

```bash
poetry run ruff check .
poetry run ruff format .
```

---

## 📋 Roadmap

- [x] Core MCP server scaffold
- [x] `get_resources` — filtered resource queries
- [x] `analyze_pod` — multi-signal root cause analysis
- [x] `compare_deployments` — cross-environment diffing
- [x] `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](CONTRIBUTING.md) for guidelines.

Please read our [Code of Conduct](CODE_OF_CONDUCT.md).

---

## 📄 License

[MIT](LICENSE)

