# 🔭 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": []
    }
  }
}
```

#### Cursor

Add to Cursor Settings → MCP:

```json
{
  "mcpServers": {
    "k8s-lens": {
      "command": "k8s-lens-mcp",
      "args": []
    }
  }
}
```

### 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."

---

## 🛡️ 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
```

---

## 🏗️ 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)