Multi Cluster Kubernetes MCP Server

An MCP (Model Context Protocol) server for managing multiple Kubernetes clusters simultaneously. Provides 60+ tools covering cluster operations, resource management, monitoring, RBAC, storage, networking, and more -- all accessible through AI assistants like Claude Desktop.

Quick Start

Installing via Smithery

npx -y @smithery/cli install @razvanmacovei/k8s-multicluster-mcp --client claude

Manual Installation

git clone https://github.com/razvanmacovei/k8s-multicluster-mcp.git
cd k8s-multicluster-mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python3 app.py

Docker

docker build -t k8s-mcp .
docker run -v ~/.kube:/root/.kube k8s-mcp

Configuration

Claude Desktop / MCP Client

Add to your MCP client configuration:

{
  "mcpServers": {
    "kubernetes": {
      "command": "python3",
      "args": ["/path/to/k8s-multicluster-mcp/app.py"],
      "env": {
        "KUBECONFIG_DIR": "/path/to/your/kubeconfigs"
      }
    }
  }
}

Environment Variables

Place your kubeconfig files in the configured directory. The server discovers all contexts across all files automatically.

Prerequisites

• Python 3.11 or higher
• One or more kubeconfig files with valid cluster credentials
• metrics-server installed in clusters for k8s_top_* and k8s_cluster_info tools

Multi-Cluster Management

This server is purpose-built for managing multiple Kubernetes clusters:

• Automatic Discovery: Scans all kubeconfig files in KUBECONFIG_DIR and aggregates contexts
• Partial Name Matching: Use prod instead of arn:aws:eks:us-east-1:123456:cluster/prod-cluster
• Cross-Cluster Operations: Compare resources, health, and configurations across clusters
• Context Caching: Efficient 30-second TTL cache avoids re-reading kubeconfig files on every call
• Centralized Management: Manage dev, staging, and production from a single interface

Tools Reference (60+ tools)

Cluster & Context Management (6 tools)

Resource Discovery & Inspection (7 tools)

Metrics & Monitoring (3 tools)

Rollout Management (6 tools)

Scaling (3 tools)

Resource CRUD (6 tools)

Workload Management (3 tools)

Node Management (5 tools)

Pod Operations (1 tool)

Secrets & ConfigMaps (6 tools)

RBAC (5 tools)

Storage (3 tools)

Networking (1 tool)

Job Management (2 tools)

Usage Examples

Cluster Health Check

Give me a health overview of my production cluster.

Multi-Cluster Comparison

Compare the number of pods running in the 'backend' namespace between my 'prod' and 'staging' contexts.

Diagnose Application Issues

My deployment 'my-app' in the 'production' namespace is having issues. Can you diagnose what's wrong?

Scale Resources

Scale the 'backend' deployment in the 'default' namespace to 5 replicas.

Resource Management

Delete the failed job 'data-migration-v1' in the 'batch' namespace.

Create a new namespace called 'staging' with the label environment=staging.

Secret Management

List all secrets in the 'production' namespace and show me the keys in the 'api-credentials' secret.

RBAC Inspection

Show me all role bindings in the 'default' namespace -- who has access to what?

Storage Overview

List all PVCs in the cluster and show which ones are Pending.

Node Maintenance

Cordon node 'worker-3', drain it ignoring DaemonSets, then uncordon when maintenance is complete.

Rollback Deployment

Roll back the 'api-gateway' deployment in the 'services' namespace to the previous version.

Execute in Pod

Run 'ls -la /app/config' inside the 'app' container of pod 'web-app-xyz' in the 'default' namespace.

Create Resources

Create a new deployment with this YAML:
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
  namespace: default
spec:
  replicas: 2
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.27
        ports:
        - containerPort: 80

Architecture

k8s-multicluster-mcp/
├── app.py                          # MCP server entry point & tool registration
├── src/
│   ├── utils/
│   │   ├── k8s_client.py           # Multi-cluster client with context caching
│   │   └── pluralize.py            # Kubernetes resource kind pluralization
│   └── tools/
│       ├── contexts.py             # Context listing
│       ├── namespaces.py           # Namespace listing
│       ├── namespace_management.py # Namespace create/delete
│       ├── nodes.py                # Node listing
│       ├── pods.py                 # Resource listing & pod logs
│       ├── resources.py            # Single resource retrieval
│       ├── events.py               # Event listing
│       ├── describe.py             # kubectl describe equivalent
│       ├── api_discovery.py        # API & CRD discovery
│       ├── metrics.py              # Node/pod metrics (top)
│       ├── diagnosis.py            # Application diagnostics
│       ├── cluster_health.py       # Cluster health summary
│       ├── rollouts.py             # Rollout management
│       ├── scaling.py              # Scale & autoscale & resource updates
│       ├── resource_management.py  # Create, apply, patch, label, annotate
│       ├── delete_resource.py      # Resource deletion
│       ├── workload_management.py  # Expose, run pod, set resources
│       ├── node_management.py      # Cordon, drain, taint
│       ├── pod_operations.py       # Exec into pods
│       ├── secret_configmap.py     # Secret & ConfigMap management
│       ├── rbac.py                 # Roles, bindings, service accounts
│       ├── storage_network.py      # PVC, PV, StorageClass, NetworkPolicy
│       └── job_management.py       # Jobs & CronJobs
├── requirements.txt
├── pyproject.toml
├── Dockerfile
└── smithery.yaml

What's New in v2.0.0

• 20+ new tools: Resource deletion, namespace management, secrets & configmaps, RBAC inspection, storage & network visibility, job management, cluster health summary, pod creation
• Bug fixes: Fixed resource pluralization (e.g., Ingress -> ingresses not ingresss), fixed pod exec command splitting to handle quoted arguments, fixed timeout parameter handling
• Performance: Context discovery now uses a 30-second TTL cache with direct context-to-file mapping, eliminating redundant file scanning
• Improved tool descriptions: All 60+ tools have detailed descriptions for better AI assistant integration
• Dependency cleanup: Removed unused fastapi and uvicorn dependencies
• Security: Namespace deletion protects system namespaces; secret values hidden by default

Contributing

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