k8s-mcp

AI-native Kubernetes operations for agents and fast-moving teams.

k8s-mcp is a lightweight MCP server that lets AI assistants deploy, inspect, and operate Kubernetes workloads through high-level workflow tools instead of raw kubectl commands — with structured outputs that significantly reduce token usage.

Works with Claude Code · Codex CLI · Gemini CLI · Opencode · and any MCP-compatible agent.

Less kubectl. More done.

Demo

Why This Exists

AI assistants today can suggest kubectl commands. But actually operating a cluster still means switching contexts, copy-pasting commands, manually debugging failures, and repeatedly checking logs and events. That creates a slow human-in-the-loop cycle.

k8s-mcp closes this gap by giving AI agents task-complete tools instead of low-level primitives. Instead of chaining:

kubectl get pod
kubectl describe pod
kubectl logs

agents can call tools like diagnose_pod() or wait_for_ready() — and get structured results in one shot.

What makes it different

k8s-mcp is designed around workflows, not raw resource access — optimized for:

• AI agent execution loops — deploy, observe, diagnose, retry, validate

• Lower token usage — structured outputs instead of long shell transcripts

• Beginner-friendly operations — less manual command chaining

• Faster iteration — fewer moving pieces between "please deploy this" and a working result

Key capabilities

• Faster and lighter than shell tools — native MCP tools return structured data directly to the AI, avoiding shell spawning, CLI output parsing, and large text streaming

• Diagnose issues in one shot — diagnose_pod combines status, conditions, events, and failing-container logs into a single report

• Autonomous deploy loops — apply manifests, wait for readiness, detect failures, and iterate without manual back-and-forth

• Generate deployment manifests — create a working Kubernetes starting point automatically instead of writing YAML from scratch

• Query and take action — list pods, read logs, inspect configs, scale deployments, restart workloads, apply manifests, and delete resources from the conversation

• Detect config drift — export live resources as YAML and compare against local manifests

• Secure by Design — reuses your ~/.kube/config and your organization's existing auth flow (SSO, OIDC, certificate). Never stores or manages credentials

• Work with any MCP client — supports stdio, HTTP, and SSE transports

How it compares

Some Kubernetes MCP servers focus on broad resource-level API access. k8s-mcp focuses on workflow-level tools designed for AI agents.

Who Is This For

• AI engineers building agent workflows that interact with Kubernetes

• Researchers deploying models on Kubernetes without deep k8s expertise

• Developers who want to automate cluster operations from their IDE

• Teams experimenting with AI-driven DevOps

If you want broad, low-level Kubernetes API access, there are other MCP servers better suited for that. If you want an agent that can actually operate a cluster with less manual overhead, this project is for you.

Quick Start

1. Install

git clone git@github.com:jingyanjiang/k8s-mcp.git
cd k8s-mcp
pipx install .

This puts k8s-mcp on your PATH and works from any directory.

You can also use uv tool install . or pip install .. For development, use poetry install.

2. Verify your Kubernetes access

k8s-mcp reads your existing ~/.kube/config. Before using it, verify:

kubectl auth whoami
kubectl get all -n <your-namespace>

The server inherits whatever permissions your kubeconfig user has. No additional credentials are needed.

Note: Some operations (e.g., list_namespaces, list_nodes) require cluster-wide permissions. If a request fails with 403 Forbidden, ask your cluster admin for the necessary RBAC roles.

3. Add to your MCP client

Claude Code / Claude Desktop

Add to .mcp.json (project-level) or ~/.claude.json (global):

{
  "mcpServers": {
    "k8s": {
      "type": "stdio",
      "command": "k8s-mcp",
      "args": ["--transport", "stdio"]
    }
  }
}

OpenAI Codex CLI

Add to ~/.codex/config.toml (user-level) or .codex/config.toml (project-level):

[mcp_servers.k8s]
command = "k8s-mcp"
args = ["--transport", "stdio"]

Gemini CLI

Add to ~/.gemini/settings.json (user-level) or .gemini/settings.json (project-level):

{
  "mcpServers": {
    "k8s": {
      "command": "k8s-mcp",
      "args": ["--transport", "stdio"]
    }
  }
}

Opencode

Add to opencode.json in your project root:

{
  "mcp": {
    "k8s": {
      "type": "local",
      "command": ["k8s-mcp", "--transport", "stdio"]
    }
  }
}

If your MCP client can't find k8s-mcp on PATH, use the absolute path instead (run which k8s-mcp to find it).

The server starts automatically when your MCP client connects — no manual commands needed.

Replace "command": "k8s-mcp" with "command": "poetry" and set args to ["run", "k8s-mcp", "--transport", "stdio"]. You must also add "cwd": "/absolute/path/to/k8s-mcp" so Poetry can find the project.

The server supports three transport modes:

# stdio (for local MCP clients like Claude Code)
k8s-mcp --transport stdio

# Streamable HTTP (for remote/networked clients)
k8s-mcp --transport streamable-http

# SSE (Server-Sent Events)
k8s-mcp --transport sse

For HTTP transports, configure bind address and port via environment variables:

export K8S_MCP_HOST=0.0.0.0   # default: localhost
export K8S_MCP_PORT=8000       # default: 8000

4. (Optional) Install the k8s-ops skill for Claude Code

For Claude Code users, this repo ships an opinionated workflow skill at skills/k8s-ops/. It encodes multi-step playbooks for deploy, debug, rollout, and audit on top of the raw MCP tools — useful when you want the agent to follow a tested sequence (e.g., debug decision tree, pre-flight rollout checks) rather than improvise.

Install with a symlink so updates from git pull flow through automatically:

ln -s "$(pwd)/skills/k8s-ops" ~/.claude/skills/k8s-ops

Then in Claude Code, invoke it with /k8s-ops (e.g., /k8s-ops debug, /k8s-ops audit NAMESPACE=foo). The skill is also model-invoked — it activates automatically when you ask the agent to deploy, diagnose, restart, or audit Kubernetes workloads.

Skip this step if you're using a different MCP client. The MCP server itself works without it.

5. Try it out

Please check the status of my namespace: <namespace>

Please deploy the app in this repo to my k8s cluster. Make a plan first, then implement it.

My pods in namespace X keep crashing. Can you figure out what's wrong?

Sample Use Cases

Check cluster status

"Please check the status of my namespace: xxxxx"

The assistant will list pods, deployments, services, and events in the namespace, surfacing any issues it finds.

Deploy an application

"Please deploy the app/server in this repo to a k8s cluster for me. Make a plan first, then implement it."

The agent will:

1. Analyze the repo structure

2. Confirm the target cluster, namespace, image registry, and tag

3. Generate Kustomize manifests

4. Apply the deployment

5. Wait for readiness and return structured health results

Diagnose a failing workload

"My pods in namespace X keep crashing. Can you figure out what's wrong?"

The agent will inspect pod status, conditions, events, and container logs — then return a structured explanation with suggested fixes. No more manually running describe and logs in a loop.

Tools

Signature tools

These best represent the project's workflow-oriented design:

All operations are exposed as MCP tools — you interact with them conversationally through your AI assistant.

Cluster Context

Namespaces

Pods

Deployments

Services

ConfigMaps

Secrets

ServiceAccounts

RBAC (Roles & Bindings)

Nodes

Events

Jobs

Ingresses

Generic Operations

Resource Metrics

Readiness

Deployment Generation

Safety

k8s-mcp is designed with practical safeguards:

• Namespace scoping — agents confirm the target namespace before taking action

• Destructive action confirmation — delete, scale-to-zero, and restart operations require explicit user approval

• Read-only queries by default — most tools are non-destructive

Always review actions before applying changes in production environments.

Project Status

This project is actively maintained and evolving. Feedback, suggestions, and contributions are welcome.

Contributing

Pull requests and ideas are welcome. If you're experimenting with AI-driven DevOps, I'd love to hear what workflows would be useful.

License

MIT