niradler/k8s-explorer-mcp

# Install from PyPI (recommended)
uv pip install k8s-explorer-mcp

# Or install from source
git clone https://github.com/nirwo/k8s-explorer-mcp.git
cd k8s-explorer-mcp
uv pip install -e ".[dev]"

{
  "mcpServers": {
    "k8s-explorer-mcp": {
      "command": "uvx",
      "args": [
        "--no-cache",
        "k8s-explorer-mcp"
      ]
    }
  }
}

{
  "mcpServers": {
    "k8s-explorer": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/k8s-explorer-mcp",
        "run",
        "server.py"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

from k8s_explorer import K8sClient, K8sCache, RelationshipDiscovery
import asyncio

async def main():
    cache = K8sCache(resource_ttl=60, max_size=2000)
    client = K8sClient(cache=cache)
    discovery = RelationshipDiscovery(client)
    
    # Get a resource
    pods = await client.list_resources(
        kind="Pod",
        namespace="default",
        label_selector="app=nginx"
    )
    
    # Discover relationships
    if pods:
        relationships = await discovery.discover_relationships(pods[0])
        for rel in relationships:
            print(f"{rel.relationship_type}: {rel.target.kind}/{rel.target.name}")
    
    # Build resource tree
    from k8s_explorer.models import ResourceIdentifier
    resource_id = ResourceIdentifier(kind="Deployment", name="nginx", namespace="default")
    tree = await discovery.build_resource_tree(resource_id, max_depth=3)
    
    stats = client.get_cache_stats()
    print(f"Cache hit rate: {stats['hit_rate_percent']}%")

asyncio.run(main())

# Start the server
uv run server.py

# Or with make
make run

# Pod was recreated with different suffix? No problem!
get_resource("Pod", "myapp-deployment-abc123-old999", "default")

# Automatically finds and returns:
# {
#   "name": "myapp-deployment-def456-xyz789",
#   "match_info": {
#     "fuzzy_match_used": true,
#     "original_name": "myapp-deployment-abc123-old999",
#     "matched_name": "myapp-deployment-def456-xyz789",
#     "similarity_score": 1.0,
#     "match_reason": "exact_base_match",
#     "explanation": "Pod 'myapp-deployment-abc123-old999' not found, but found 
#                     'myapp-deployment-def456-xyz789' with same base name 
#                     'myapp-deployment'. This is likely a newer instance."
#   }
# }

# Search for pods by pattern (fuzzy matching built-in)
get_resource("Pod", "cronjob-backup", "default")

# Automatically finds similar pods with similarity scores
# Handles: Deployments, StatefulSets, Jobs, CronJobs suffixes

# Get complete context for debugging (smart matching included)
discover_resource("Pod", "my-app-xyz", "production", depth="complete")

# Returns:
# - ConfigMaps it needs (and if they exist)
# - Secrets it uses (with mount details)
# - Parent Deployment/ReplicaSet
# - Helm chart managing it
# - Complete failure context with explanations
# - Match info if pod name was fuzzy matched

# Get pod logs (with automatic container detection)
get_pod_logs("my-app-xyz", "production", tail=200)

# Returns:
# - Logs from the pod (auto-detects single container)
# - Pod status and container list
# - Truncation info
# - Match info if fuzzy matching was used

# What changed in the last deployment?
get_resource_changes("Deployment", "nginx-deployment", "production", max_versions=3)

# Returns:
# {
#   "latest_changes": {
#     "from_revision": "5",
#     "to_revision": "6",
#     "summary": "2 field(s) modified",
#     "changes": [
#       {
#         "field": "spec.replicas",
#         "change_type": "modified",
#         "old_value": "3",
#         "new_value": "5",
#         "delta": 2,
#         "percent_change": 66.67
#       },
#       {
#         "field": "spec.template.spec.containers[0].image",
#         "change_type": "modified",
#         "old_value": "nginx:1.21",
#         "new_value": "nginx:1.22"
#       }
#     ]
#   },
#   "timeline": [...],  # History of all changes
#   "note": "Use max_versions to control how far back to look"
# }

# Compare specific versions
compare_resource_versions("Deployment", "nginx", "prod", from_revision=3, to_revision=5)

# Get full change history (defaults to last 5 versions)
get_resource_changes("Deployment", "nginx", "prod")
# Returns: Timeline of changes with diffs

# What will break if I delete this ConfigMap?
discover_resource("ConfigMap", "app-config", "prod", depth="tree")

# Shows:
# - All Deployments using it
# - All ReplicaSets affected
# - All Pods that will restart

# Quick check of dependencies
discover_resource("Secret", "db-password", "prod", depth="relationships")
# Fast list of all resources using this secret

# Debug Airflow DAG - find related resources
list_resources("Pod", "airflow", labels={"dag_id": "etl-pipeline"})

# Debug Argo Workflow - full context
discover_resource("Workflow", "data-processing", "workflows", depth="complete")

# Debug Helm release - shows chart, version, all managed resources
discover_resource("Deployment", "nginx", "default", depth="complete")
# Returns: Helm release name, chart version, all related resources

# Run all tests
make test

# Run with coverage report
make test-cov

# Run specific test file
pytest tests/test_cache.py

# Install with dev dependencies
make install-dev

# Format code
make format

# Lint code
make lint

# Run all checks
make check