Kubernetes MCP

An MCP server that exposes common Kubernetes inspection and deployment operations to an MCP client.

The project is designed for local Kind clusters. It connects to the kubeconfig context in the KUBERNETES_CONTEXT environment variable, defaulting to kind-dev101.

Features

The server provides these MCP tools:

Related MCP server: mcp-kubernetics

Prerequisites

• Python 3.13 or later

• uv

• Docker

• Kind

• kubectl

Create the Kind clusters

Create the local clusters from PowerShell or a terminal:

kind create cluster --name dev101
kind create cluster --name sit101
kind create cluster --name prod101

Kind creates these kubeconfig contexts:

kind-dev101
kind-sit101
kind-prod101

Verify the contexts:

kubectl config get-contexts

Install dependencies

From the repository root:

uv sync

Run the MCP server

Start the server over the standard MCP stdio transport:

uv run python src/kubernetes_mcp/__init__.py

The server reads the Kubernetes configuration from the default kubeconfig location. Set KUBERNETES_CONTEXT before launching it to choose a cluster:

PowerShell:

$env:KUBERNETES_CONTEXT = "kind-sit101"
uv run python src/kubernetes_mcp/__init__.py

For production, use kind-prod101. If the variable is omitted, the server connects to kind-dev101.

Configure an MCP client

Add the server to an MCP client that supports stdio servers. The command should point to this repository and use the same launcher shown above:

{
	"mcpServers": {
		"kubernetes": {
			"command": "uv",
			"env": {
				"KUBERNETES_CONTEXT": "kind-sit101"
			},
			"args": [
				"run",
				"--directory",
				"C:\\Users\\<your-user>\\kubernetes-mcp",
				"python",
				"src/kubernetes_mcp/__init__.py"
			]
		}
	}
}

Replace the repository path with the path on your machine. Keep the MCP server process attached to the client; it communicates through stdin and stdout.

Deploy the sample workload

The repository includes an NGINX deployment and service in k8s/deployment.yaml:

kubectl config use-context kind-dev101
kubectl apply -f k8s/deployment.yaml
kubectl get deployments,pods,services -n default

The sample deployment is named nginx and runs two replicas.

Example tool calls

Use the MCP client to call tools with arguments such as:

{
	"namespace": "default",
	"deployment": "nginx",
	"replicas": 3
}

This payload can be used with scale_deployment to scale NGINX to three replicas. To restart the deployment, call restart_deployment with:

{
	"namespace": "default",
	"deployment": "nginx"
}

Switching clusters

Set KUBERNETES_CONTEXT in the MCP client configuration and restart the server process. For example, use kind-dev101, kind-sit101, or kind-prod101. The MCP server uses the selected context directly, regardless of which context is active in kubectl.

Stop and delete clusters

To stop using the local clusters and remove their containers:

kind delete cluster --name dev101
kind delete cluster --name sit101
kind delete cluster --name prod101

Deleting a Kind cluster removes its local Kubernetes resources. Do not run these commands for a cluster containing data you need to keep.