MCP + Kubernetes: A Step-by-Step Tutorial on Connecting AI Agents to Your Cluster

The Model Context Protocol (MCP) has quickly become one of the most talked-about topics at recent CNCF and KubeCon hallway tracks. It gives AI assistants a standard way to call tools and read live data, and Kubernetes is a perfect target: instead of copy-pasting kubectl output into a chat window, you can let an AI agent query and even operate your cluster directly through a well-scoped MCP server. This tutorial walks through wiring up an MCP server for Kubernetes from scratch.

What you will build

By the end of this tutorial you will have a local Kubernetes cluster, an MCP server exposing cluster read/write operations as tools, and an AI client (such as Claude Desktop) that can answer natural-language questions about your workloads and, with your approval, apply changes.

Prerequisites

• Docker Desktop or another container runtime installed
• kubectl installed and configured
• kind or minikube for a disposable local cluster
• Node.js 18+ or Python 3.10+ (most MCP servers ship in one of these)
• An MCP-capable client, for example Claude Desktop

Step 1: Spin up a local cluster

Create a throwaway cluster so you are free to experiment safely.

kind create cluster --name mcp-demo
kubectl get nodes

Step 2: Install an MCP server for Kubernetes

Several community MCP servers wrap kubectl and the Kubernetes API. Install one into a virtual environment or via npm, then verify it starts locally.

pip install mcp-server-kubernetes
mcp-server-kubernetes --kubeconfig ~/.kube/config --readonly

Starting with the --readonly flag is a good habit while you learn how the server behaves.

Step 3: Register the server with your AI client

Most desktop MCP clients read a small JSON config file that lists the servers to launch. Add an entry similar to this one and restart the client.

{
  "mcpServers": {
    "kubernetes": {
      "command": "mcp-server-kubernetes",
      "args": ["--kubeconfig", "/Users/you/.kube/config", "--readonly"]
    }
  }
}

Step 4: Ask your cluster questions in plain English

Open a chat with your AI client and try prompts like “list pods that are not Running” or “show me the last 20 log lines for the frontend deployment”. The assistant translates these into tool calls against the MCP server and returns structured answers.

Step 5: Lock down access before going further

Before connecting MCP to anything beyond a sandbox, create a dedicated ServiceAccount with a narrowly scoped Role instead of reusing your admin kubeconfig.

apiVersion: v1
kind: ServiceAccount
metadata:
  name: mcp-agent
  namespace: default
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: mcp-agent-reader
  namespace: default
rules:
- apiGroups: [""]
  resources: ["pods", "services", "events"]
  verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: mcp-agent-reader-binding
  namespace: default
subjects:
- kind: ServiceAccount
  name: mcp-agent
roleRef:
  kind: Role
  name: mcp-agent-reader
  apiGroup: rbac.authorization.k8s.io

Only graduate the agent to write access, such as scaling deployments or restarting pods, once you trust the prompts you are sending and have audit logging enabled.

Wrap-up

You now have a working MCP bridge between an AI assistant and a real Kubernetes cluster, starting in read-only mode and layered with RBAC before any write access is granted. This pattern of natural-language operations backed by narrowly scoped credentials is exactly the direction the CNCF community has been exploring for AI-assisted cluster operations.

Further Reading & Resources

• Model Context Protocol – official docs and specification
• mcp-server-kubernetes on GitHub – the MCP server used in this tutorial
• Kubernetes RBAC documentation – lock down what your MCP agent can touch
• kind – Kubernetes in Docker – spin up the local test cluster used here
• Kubernetes official documentation
• CNCF – Cloud Native Computing Foundation