k8s-mcp
A Python-based, read-only Model Context Protocol (MCP) server for Kubernetes clusters that exposes a comprehensive API to retrieve cluster information and diagnose issues.
Installation
Prerequisites
- Python 3.8+
- Access to a Kubernetes cluster (via kubeconfig or in-cluster configuration)
- Required Python packages (see
dependenciesinpyproject.toml) - uv - https://github.com/astral-sh/uv
# To install uv
curl -LsSf https://astral.sh/uv/install.sh | sh
# Clone the repository
git clone git@github.com:vlttnv/k8s-mcp.git
cd k8s-mcp
# Install dependencies
uv venv
source .venv/bin/activate
uv sync
If using Claude configure open your Claude for Desktop App configuration at ~/Library/Application Support/Claude/claude_desktop_config.json in a text editor. Make sure to create the file if it doesn’t exist.
code ~/Library/Application\ Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"k8s-mcp": {
"command": "uv",
"args": [
"--directory",
"/ABSOLUTE/PATH/TO/PARENT/FOLDER/k8s-mcp",
"run",
"server.py"
]
}
}
}
You may need to put the full path to the uv executable in the command field. You can get this by running which uv on MacOS/Linux or where uv on Windows.
Configuration
The application automatically tries two methods to connect to your Kubernetes cluster:
- Kubeconfig File: Uses your local kubeconfig file (typically located at
~/.kube/config) - In-Cluster Configuration: If running inside a Kubernetes pod, uses the service account token
No additional configuration is required if your kubeconfig is properly set up or if you're running inside a cluster with appropriate RBAC permissions.
Usage
Examples
Here are some useful example prompts you can ask Claude about your Kubernetes cluster and its resources:
General Cluster Status
- "What's the overall health of my cluster?"
- "Show me all namespaces in my cluster"
- "What nodes are available in my cluster and what's their status?"
- "How is resource utilization across my nodes?"
Pods and Deployments
- "List all pods in the production namespace"
- "Are there any pods in CrashLoopBackOff state?"
- "Show me pods with high restart counts"
- "List all deployments across all namespaces"
- "What deployments are failing to progress?"
Debugging Issues
- "Why is my pod in the staging namespace failing?"
- "Get the YAML configuration for the service in the production namespace"
- "Show me recent events in the default namespace"
- "Are there any pods stuck in Pending state?"
- "What's causing ImagePullBackOff errors in my cluster?"
Resource Management
- "Show me the resource consumption of nodes in my cluster"
- "Are there any orphaned resources I should clean up?"
- "List all services in the production namespace"
- "Compare resource requests between staging and production"
Specific Resource Inspection
- "Show me the config for the coredns deployment in kube-system"
- "Get details of the reverse-proxy service in staging"
- "What containers are running in the pod xyz?"
- "Show me the logs for the failing pod"
API Reference
Namespaces
get_namespaces(): List all available namespaces in the cluster
Pods
list_pods(namespace=None): List all pods, optionally filtered by namespacefailed_pods(): List all pods in Failed or Error statepending_pods(): List all pods in Pending state with reasonshigh_restart_pods(restart_threshold=5): Find pods with restart counts above threshold
Nodes
list_nodes(): List all nodes and their statusnode_capacity(): Show available capacity on all nodes
Deployments & Services
list_deployments(namespace=None): List all deploymentslist_services(namespace=None): List all serviceslist_events(namespace=None): List all events
Resource Management
orphaned_resources(): List resources without owner referencesget_resource_yaml(namespace, resource_type, resource_name): Get YAML configuration for a specific resource
License
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.