k8s-mcp

You run a Python-based MCP server for Kubernetes to retrieve cluster data and diagnose issues. This server exposes a clean API you can query from an MCP client to inspect namespaces, pods, nodes, deployments, services, events, and resource ownership. It is designed to be read-only and focused on diagnostics, making it easy to monitor and troubleshoot your Kubernetes cluster from a centralized MCP interface.

How to use

Start by configuring your MCP client to connect to the k8s MCP server via a local stdio workflow. You will run the MCP adapter through the UV tool, which starts the server script and exposes the MCP endpoints through the client interface. The server provides commands to list namespaces, pods, nodes, deployments, services, and events, as well as helpers to identify orphaned resources and YAML configurations for specific resources.

How to install

Prerequisites you need before installing and running the MCP server:

• Python 3.8+
• Access to a Kubernetes cluster (via kubeconfig or in-cluster configuration)
• uv tool installed (https://github.com/astral-sh/uv)

Steps to set up and run the MCP server

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

# Clone the MCP server repository
git clone git@github.com:vlttnv/k8s-mcp.git
cd k8s-mcp

# Set up a Python virtual environment and install dependencies via uv
uv venv
source .venv/bin/activate
uv sync

# Start the MCP server through the UV runner using the configuration shown below

Claude client configuration example

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

Configuration notes

The server automatically attempts two Kubernetes connection methods: the local kubeconfig file (typically at ~/.kube/config) and in-cluster configuration when running inside a pod with proper RBAC permissions. No additional configuration is required if your kubeconfig is valid or your pod has access to the cluster.

API and usage concepts

Use the MCP client to query cluster state and diagnostics. Typical capabilities include listing namespaces, pods (with filters for status like Failed, Pending, or CrashLoopBackOff), nodes with capacity, deployments, services, and events. You can also fetch resource YAMLs and identify orphaned resources that lack an owner reference.

Security and access

Operate with appropriate RBAC permissions when running inside a cluster. Treat the MCP server as read-only for safety to avoid unintended modifications in production environments.

Troubleshooting notes

If you cannot connect to the cluster, verify that your kubeconfig is accessible from the environment running the MCP server. If running in-cluster, confirm that the service account has the necessary permissions to read cluster resources.

Notes

This MCP server focuses on providing a comprehensive, read-only view of Kubernetes cluster state and diagnostics through a stable API that MCP clients can consume for monitoring and troubleshooting.

API Reference highlights

Namespaces, Pods, Nodes, Deployments, Services and Events endpoints are exposed to help you quickly summarize cluster health, identify problematic resources, and inspect specific resources with YAML details or events.

License

MIT License

Contributing

Contributions are welcome! Submit a Pull Request to add features, fix issues, or improve documentation.

Available tools

get_namespaces

List all available namespaces in the cluster

list_pods

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

Find pods with restart counts above a threshold (default 5)

list_nodes

List all nodes and their status

node_capacity

Show available capacity on all nodes

list_deployments

List all deployments across namespaces

list_services

List all services across namespaces

list_events

List all events across namespaces

orphaned_resources

List resources without owner references

get_resource_yaml

Get YAML configuration for a specific resource by namespace, type, and name