Kubernetes Monitoring MCP server for AI agents

This Python-based Model Context Protocol (MCP) server for Kubernetes provides a comprehensive API that allows AI assistants like Claude to retrieve cluster information and diagnose issues. It connects to your Kubernetes clusters and exposes detailed information about resources, helping streamline management and troubleshooting tasks.

Installation

Prerequisites

Python 3.8+
Access to a Kubernetes cluster (via kubeconfig or in-cluster configuration)
Required Python packages
uv package manager

Setup Process

First, install the uv package manager:

curl -LsSf https://astral.sh/uv/install.sh | sh

Next, clone and set up the repository:

# Clone the repository
git clone [email protected]:vlttnv/k8s-mcp.git
cd k8s-mcp

# Install dependencies
uv venv
source .venv/bin/activate
uv sync

Configure with Claude

If using Claude, configure your Claude for Desktop App by editing or creating the configuration file:

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

Add the following configuration (replace with your absolute path):

{
    "mcpServers": {
        "k8s-mcp": {
            "command": "uv",
            "args": [
                "--directory",
                "/ABSOLUTE/PATH/TO/PARENT/FOLDER/k8s-mcp",
                "run",
                "server.py"
            ]
        }
    }
}

Note: You might need to use the full path to the uv executable in the command field. Find it by running which uv on MacOS/Linux or where uv on Windows.

Configuration

The server automatically attempts to connect to your Kubernetes cluster using:

Kubeconfig File: Uses your local kubeconfig file (typically at ~/.kube/config)
In-Cluster Configuration: When running inside a Kubernetes pod, uses the service account token

No additional configuration is needed if your kubeconfig is properly set up or if you're running inside a cluster with appropriate RBAC permissions.

Usage Examples

You can interact with your Kubernetes cluster by asking Claude questions about various resources and their status.

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

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "k8s-mcp" '{"command":"uv","args":["--directory","/ABSOLUTE/PATH/TO/PARENT/FOLDER/k8s-mcp","run","server.py"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "k8s-mcp": {
            "command": "uv",
            "args": [
                "--directory",
                "/ABSOLUTE/PATH/TO/PARENT/FOLDER/k8s-mcp",
                "run",
                "server.py"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "k8s-mcp": {
            "command": "uv",
            "args": [
                "--directory",
                "/ABSOLUTE/PATH/TO/PARENT/FOLDER/k8s-mcp",
                "run",
                "server.py"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect