使用说明

mcp-kubernetes

Kubernetes MCP server providing kubectl and Helm operations via FastMCP.

Features

25 tools for comprehensive Kubernetes management
kubectl operations (get, describe, logs, apply, delete, rollout, scale, exec)
Helm support (install, upgrade, uninstall, repo management)
Node management (cordon, uncordon, drain)
Pod cleanup for problematic states (Evicted, Error, etc.)
Uses standard kubeconfig authentication

Installation

Prerequisites

Python 3.10+
uv package manager
kubectl installed and in PATH
helm installed and in PATH (optional, for Helm tools)
Valid kubeconfig with cluster access

Setup

git clone https://github.com/lyzetam/mcp-kubernetes.git
cd mcp-kubernetes
uv venv && uv pip install fastmcp

Claude Code Configuration

Add to ~/.claude.json:

{
  "mcpServers": {
    "mcp-kubernetes": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-kubernetes",
        "run",
        "python",
        "server.py"
      ],
      "env": {}
    }
  }
}

Or via CLI:

claude mcp add mcp-kubernetes -- uv --directory /path/to/mcp-kubernetes run python server.py

Authentication

The server uses standard kubectl/kubeconfig authentication:

Variable	Default	Description
`KUBECONFIG`	`~/.kube/config`	Path to kubeconfig file
`KUBE_CONTEXT`	Current context	Kubernetes context to use

Default Behavior

By default, the server uses:

Kubeconfig at ~/.kube/config
The current context set in that kubeconfig

Custom Configuration

To use a different kubeconfig or context, set environment variables in the MCP config:

{
  "mcpServers": {
    "mcp-kubernetes": {
      "type": "stdio",
      "command": "uv",
      "args": ["--directory", "/path/to/mcp-kubernetes", "run", "python", "server.py"],
      "env": {
        "KUBECONFIG": "/path/to/custom/kubeconfig",
        "KUBE_CONTEXT": "my-cluster-context"
      }
    }
  }
}

Multiple Clusters

For multiple clusters, you can either:

Use context switching - Single kubeconfig with multiple contexts, use kubectl_context tool to switch
Multiple MCP servers - Register multiple servers with different kubeconfig paths:

{
  "mcpServers": {
    "k8s-prod": {
      "command": "uv",
      "args": ["--directory", "/path/to/mcp-kubernetes", "run", "python", "server.py"],
      "env": { "KUBECONFIG": "~/.kube/prod-config" }
    },
    "k8s-staging": {
      "command": "uv",
      "args": ["--directory", "/path/to/mcp-kubernetes", "run", "python", "server.py"],
      "env": { "KUBECONFIG": "~/.kube/staging-config" }
    }
  }
}

Available Tools (25)

Status & Context

Tool	Description
`kubectl_status`	Check connection status and current context
`kubectl_context`	List or switch kubectl contexts

Read Operations

Tool	Description
`kubectl_get`	Get/list resources (pods, deployments, services, etc.)
`kubectl_describe`	Detailed resource information
`kubectl_logs`	Pod logs with tail, since, and container options
`kubectl_events`	Cluster events sorted by timestamp
`kubectl_top`	Resource usage (requires metrics-server)
`list_api_resources`	List available API resources
`explain_resource`	Explain resource types and fields

Write Operations

Tool	Description
`kubectl_apply`	Apply YAML manifests
`kubectl_create`	Create resources
`kubectl_delete`	Delete resources
`kubectl_patch`	Patch resources (strategic, merge, json)

Deployment Management

Tool	Description
`kubectl_rollout`	Rollout operations (status, restart, undo, pause, resume)
`kubectl_scale`	Scale deployments/statefulsets/replicasets

Debug & Exec

Tool	Description
`exec_in_pod`	Execute commands in pods
`port_forward_info`	Get port-forward command (returns command to run)
`kubectl_generic`	Execute arbitrary kubectl commands

Node & Cluster Operations

Tool	Description
`node_management`	Cordon, uncordon, drain nodes
`cleanup_pods`	Clean up Evicted/Error/Unknown pods

Helm Operations

Tool	Description
`helm_list`	List installed releases
`helm_install`	Install charts
`helm_upgrade`	Upgrade releases
`helm_uninstall`	Uninstall releases
`helm_repo`	Manage Helm repositories

Usage Examples

Get pods in a namespace

kubectl_get(resource="pods", namespace="default", output="wide")

Describe a deployment

kubectl_describe(resource="deployment", name="nginx", namespace="default")

Get logs from a pod

kubectl_logs(pod="nginx-abc123", namespace="default", tail=100, since="5m")

Restart a deployment

kubectl_rollout(action="restart", resource="deployment", name="nginx", namespace="default")

Scale a deployment

kubectl_scale(resource="deployment", name="nginx", replicas=3, namespace="default")

Drain a node for maintenance

node_management(action="drain", node="worker-1", ignore_daemonsets=True)

Clean up evicted pods

cleanup_pods(all_namespaces=True, states="Evicted,Error")

Install a Helm chart

helm_install(
    release_name="nginx",
    chart="bitnami/nginx",
    namespace="default",
    create_namespace=True
)

Execute command in pod

exec_in_pod(pod="nginx-abc123", namespace="default", command="cat /etc/nginx/nginx.conf")

Development

Run locally

cd mcp-kubernetes
uv run python server.py

Test tools

uv run python -c "from server import run_kubectl; print(run_kubectl(['get', 'nodes']))"

Count tools

uv run python -c "from server import mcp; print(f'Tools: {len(mcp._tool_manager._tools)}')"

License

MIT