view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

# MCP::K8s - MCP Server for Kubernetes

**RBAC-aware Kubernetes tools for AI assistants**

[![CPAN Version](https://img.shields.io/cpan/v/MCP-K8s.svg)](https://metacpan.org/release/MCP-K8s)
[![License](https://img.shields.io/cpan/l/MCP-K8s.svg)](https://metacpan.org/release/MCP-K8s)

MCP::K8s provides an [MCP](https://modelcontextprotocol.io/) (Model Context Protocol) server that gives AI assistants like Claude access to Kubernetes clusters.

The key innovation: **the server dynamically discovers what the connected service account can do via RBAC** and only exposes those capabilities as MCP tools. A read-only service account gets read-only tools; a cluster-admin gets everything.

## Quick Start

```bash
# Install
cpanm MCP::K8s

# Run (uses current kubeconfig context)
mcp-k8s

# Or with direct token authentication
MCP_K8S_TOKEN=$(kubectl create token my-sa) MCP_K8S_SERVER=https://my-cluster:6443 mcp-k8s
```

## Claude Desktop

Add to `~/.config/claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "kubernetes": {
      "command": "mcp-k8s",
      "env": {
        "MCP_K8S_CONTEXT": "my-cluster",
        "MCP_K8S_NAMESPACES": "default,production"
      }
    }
  }
}
```

## Claude Code

Add to your project's `.mcp.json`:

```json
{
  "mcpServers": {
    "kubernetes": {
      "command": "mcp-k8s",
      "env": {
        "MCP_K8S_CONTEXT": "dev-cluster"
      }
    }
  }
}
```

## How It Works

1. **Connect** — Authenticates via direct token, in-cluster service account, or kubeconfig
2. **Discover** — Submits `SelfSubjectRulesReview` requests to discover RBAC permissions per namespace
3. **Register** — Creates MCP tools with dynamic descriptions reflecting actual permissions
4. **Serve** — Runs the MCP protocol over stdio, checking permissions on every tool call

## MCP Tools

| Tool | Description |
|------|-------------|
| `k8s_permissions` | Show RBAC permissions — **call this first** |
| `k8s_list` | List resources (Pods, Deployments, Services, ...) |
| `k8s_get` | Get a single resource (summary, JSON, or YAML) |
| `k8s_create` | Create a resource from a manifest |
| `k8s_patch` | Partially update a resource (strategic/merge/JSON patch) |
| `k8s_delete` | Delete a resource |
| `k8s_logs` | Get pod container logs |
| `k8s_events` | Get events for debugging (filter by object, field selector) |
| `k8s_rollout_restart` | Trigger rolling restart of Deployment/StatefulSet/DaemonSet |
| `k8s_apply` | Create or update a resource (like `kubectl apply`) |

### Why 10 generic tools instead of hundreds?

Kubernetes has 50+ built-in resource types plus unlimited CRDs. Instead of creating specific tools (`list_pods`, `get_deployment`, `delete_configmap`...), MCP::K8s uses generic tools with a `resource` parameter — the same pattern as `kubectl get <r...

### Dynamic Tool Descriptions