# k8s-ops-mcp-agent

An **AI SRE copilot** for Kubernetes, built on the Model Context Protocol (MCP).
It lets an LLM (Claude, or any MCP-compatible agent) inspect the health of a
cluster and — only with explicit human confirmation — restart or scale
deployments.

> Built to explore how LLM agents can be given *real* operational tools
> without becoming a liability: read access is open, write access is gated.

## Why this exists

Incident response burns a lot of engineer time on repetitive diagnosis:
"which pods are crash-looping, what do the logs say, what changed recently."
This project gives an LLM agent the tools to answer that in seconds, while
keeping a human explicitly in the loop for anything destructive.

## Architecture

```
┌─────────────────┐        MCP (stdio)        ┌──────────────────────┐        Kubernetes API
│  Claude Desktop  │  ───────────────────────▶ │  k8s-ops-mcp-agent   │ ───────────────────────▶  Cluster
│  (or any MCP     │  ◀─────────────────────── │  (this repo)         │ ◀───────────────────────  (kind / EKS / etc.)
│   client)        │      tool calls/results    └──────────────────────┘
└─────────────────┘
```

The agent process talks to the cluster using the official Kubernetes Python
client and a standard kubeconfig — the same credentials you'd use with
`kubectl`. It never embeds cluster credentials in the LLM prompt.

## Tools exposed

| Tool | Type | Description |
|---|---|---|
| `list_pods` | read | Pod status, restart counts, age for a namespace |
| `get_pod_logs` | read | Tail logs for a specific pod |
| `get_events` | read | Recent Kubernetes events (crash loops, image pull errors, scheduling failures) |
| `get_deployment_status` | read | Desired vs ready vs available replicas |
| `restart_deployment` | **write** | Rolling restart — requires `confirm=True` |
| `scale_deployment` | **write** | Scale replicas (0-50 range enforced) — requires `confirm=True` |

## Safety design

This is the part I care most about — an agent with unrestricted write access
to production infrastructure is a bad idea. So:

- **Read tools require no confirmation** — an agent should be free to look
  around and diagnose.
- **Write tools refuse to execute unless called with `confirm=True`.** The
  intended flow is: agent proposes an action → human says "do it" → agent
  calls the tool again with confirmation. This is enforced in code, not just
  in the prompt, so it can't be bypassed by prompt injection from logs or
  pod output the agent reads.
- **Replica counts are hard-capped (0-50)** regardless of confirmation, as a
  last line of defense against a runaway agent loop.
- **Every tool call is logged** with timestamp and arguments for auditability.
- **Actions are always scoped to a single namespace** passed explicitly by
  the caller — there is no cluster-wide destructive tool.

See [`server/k8s_ops_server.py`](server/k8s_ops_server.py) and the tests in
[`tests/test_guardrails.py`](tests/test_guardrails.py), which specifically
verify the refusal logic (six passing tests covering confirm/no-confirm and
out-of-range scaling).

## Setup

```bash
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt

# Point at a real or local cluster (e.g. kind/minikube)
kind create cluster --name ops-demo

# Run the server directly (for local testing via MCP inspector)
python server/k8s_ops_server.py
```

To use it from Claude Desktop, add an entry to your MCP config — see
[`docs/claude_desktop_config.example.json`](docs/claude_desktop_config.example.json).

## Running the tests

```bash
python -m unittest tests/test_guardrails.py -v
```

No cluster required — the Kubernetes client is mocked so the guardrail logic
can be verified in isolation (and in CI).

## Example session

```
> "What's going on with checkout-api in staging?"

[agent calls get_deployment_status, get_pod_logs, get_events]

The checkout-api deployment has 1/3 pods ready. One pod is in
CrashLoopBackOff — the logs show a database connection timeout at startup.
Events confirm 4 restarts in the last 10 minutes. This looks like the DB
hasn't finished migrating. Want me to restart the deployment once the
migration job completes, or scale down to reduce restart pressure?

> "Yes, restart it."

[agent calls restart_deployment(confirm=True)]

Restart triggered for checkout-api in staging at 2026-07-20T14:32:01Z.
```


![Demo session](docs/screenshots/demo-session.png)

## Roadmap / possible extensions

- Slack integration so the confirmation step happens in a thread
- Read-only cost/right-sizing recommendations tool (via AWS Compute Optimizer)
- Multi-cluster support with per-cluster kubeconfig context switching

## Stack

Python · Kubernetes Python client · Model Context Protocol (MCP) · unittest