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.
Metadata
Release files for iflow-mcp_vlttnv-k8s-mcp 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| iflow_mcp_vlttnv_k8s_mcp-0.1.0.tar.gz | 11.8 kB | Without provenance | Details for iflow_mcp_vlttnv_k8s_mcp-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| iflow_mcp_vlttnv_k8s_mcp-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for iflow_mcp_vlttnv_k8s_mcp-0.1.0-py3-none-any.whl |
Total release size: 22.4 kB
Release files / iflow_mcp_vlttnv_k8s_mcp-0.1.0.tar.gz
| Download URL | iflow_mcp_vlttnv_k8s_mcp-0.1.0.tar.gz |
|---|---|
| Size | 11.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
63b20f1dd8906e8bba4ccb6a4d3b54abf3d8b9d917e3067be243edb644ee073b
|
|
BLAKE2b-256 checksum How to use checksums |
0d67b000c29639295c885460ab83e9022c81aadedb2d8cdeb5037c2ee535886b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.2 {"installer":{"name":"uv","version":"0.10.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / iflow_mcp_vlttnv_k8s_mcp-0.1.0-py3-none-any.whl
| Download URL | iflow_mcp_vlttnv_k8s_mcp-0.1.0-py3-none-any.whl |
|---|---|
| Size | 10.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b35783701ed96675a456c4ea91187a89b0e7ca1844d4e63c140c8e96a2e4eb8a
|
|
BLAKE2b-256 checksum How to use checksums |
ca5dd3ce784ba936da8799b7ea0aa7a6c5bdc013c83ba787a7544d5afcbeeaaf
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.2 {"installer":{"name":"uv","version":"0.10.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for iflow-mcp_vlttnv-k8s-mcp 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.