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.

Example chat using Claude

Installation

Prerequisites

• Python 3.8+
• Access to a Kubernetes cluster (via kubeconfig or in-cluster configuration)
• Required Python packages (see dependencies in pyproject.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 [email protected]: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:

1. Kubeconfig File: Uses your local kubeconfig file (typically located at ~/.kube/config)
2. 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 namespace
• failed_pods(): List all pods in Failed or Error state
• pending_pods(): List all pods in Pending state with reasons
• high_restart_pods(restart_threshold=5): Find pods with restart counts above threshold

Nodes

• list_nodes(): List all nodes and their status
• node_capacity(): Show available capacity on all nodes

Deployments & Services

• list_deployments(namespace=None): List all deployments
• list_services(namespace=None): List all services
• list_events(namespace=None): List all events

Resource Management

• orphaned_resources(): List resources without owner references
• get_resource_yaml(namespace, resource_type, resource_name): Get YAML configuration for a specific resource

License

MIT License

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.