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

Variable	Default	Description
KUBECONFIG_DIR	~/.kube	Directory containing kubeconfig files. Each file can contain one or more contexts.

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)

Tool	Description
k8s_get_contexts	List all available contexts across all kubeconfig files
k8s_get_namespaces	List all namespaces in a cluster
k8s_create_ns	Create a new namespace with optional labels/annotations
k8s_delete_ns	Delete a namespace (protects system namespaces)
k8s_get_nodes	List all nodes with status, roles, capacity, and version
k8s_cluster_info	Comprehensive cluster health summary (nodes, pods, deployments, warnings)

Resource Discovery & Inspection (7 tools)

Tool	Description
k8s_get_resources	List resources of any kind (pods, deployments, services, ingress, etc.)
k8s_get_resource	Get the complete definition of a single resource
k8s_get_pod_logs	Get pod logs with duration filtering and container selection
k8s_get_events	List cluster events in a namespace, sorted by most recent
k8s_describe	Detailed resource description similar to kubectl describe
k8s_apis	List all available API groups and resources in the cluster
k8s_crds	List all Custom Resource Definitions with versions and scope

Metrics & Monitoring (3 tools)

Tool	Description
k8s_top_nodes	Display node CPU/memory usage alongside capacity
k8s_top_pods	Display pod/container CPU/memory usage
k8s_diagnose_application	Comprehensive app diagnostics with issue detection and recommendations

Rollout Management (6 tools)

Tool	Description
k8s_rollout_status	Get rollout status for deployment/statefulset/daemonset
k8s_rollout_history	Get revision history
k8s_rollout_undo	Roll back to a previous revision
k8s_rollout_restart	Trigger a rolling restart
k8s_rollout_pause	Pause an in-progress rollout
k8s_rollout_resume	Resume a paused rollout

Scaling (3 tools)

Tool	Description
k8s_scale_resource	Scale deployment/statefulset/replicaset to N replicas
k8s_autoscale_resource	Configure Horizontal Pod Autoscaler (HPA)
k8s_update_resources	Update CPU/memory requests and limits for a container

Resource CRUD (6 tools)

Tool	Description
k8s_create_resource	Create a resource from YAML/JSON content
k8s_apply_resource	Apply configuration (create or update, like kubectl apply)
k8s_delete_resource	Delete any resource type with optional force/grace period
k8s_patch_resource	Update specific fields with strategic merge patch
k8s_label_resource	Add or update labels on a resource
k8s_annotate_resource	Add or update annotations on a resource

Workload Management (3 tools)

Tool	Description
k8s_expose_resource	Expose a deployment/pod as a new Service
k8s_run_pod	Create and run a pod with a specified image
k8s_set_resources_for_container	Set resource limits/requests for containers

Node Management (5 tools)

Tool	Description
k8s_cordon_node	Mark a node as unschedulable
k8s_uncordon_node	Mark a node as schedulable
k8s_drain_node	Drain a node by evicting pods (for maintenance)
k8s_taint_node	Add taints to a node
k8s_untaint_node	Remove taints from a node

Pod Operations (1 tool)

Tool	Description
k8s_pod_exec	Execute a command in a container (supports quoted arguments)

Secrets & ConfigMaps (6 tools)

Tool	Description
k8s_list_secret	List secrets with metadata (values hidden for security)
k8s_get_secret_detail	Get a secret; optionally decode values
k8s_create_secret_resource	Create a new secret (auto base64-encodes values)
k8s_list_configmap	List ConfigMaps with their key names
k8s_get_configmap_detail	Get a ConfigMap with full data contents
k8s_create_configmap_resource	Create a new ConfigMap

RBAC (5 tools)

Tool	Description
k8s_get_roles	List RBAC Roles with permission rules
k8s_get_clusterroles	List RBAC ClusterRoles
k8s_get_rolebindings	List RoleBindings (who has what role)
k8s_get_clusterrolebindings	List ClusterRoleBindings
k8s_get_service_accounts	List ServiceAccounts

Storage (3 tools)

Tool	Description
k8s_get_pvcs	List PersistentVolumeClaims with status, capacity, and storage class
k8s_get_pvs	List PersistentVolumes with capacity and bound claims
k8s_get_storage_classes	List StorageClasses with provisioner and default status

Networking (1 tool)

Tool	Description
k8s_get_network_policies	List NetworkPolicies with pod selectors and rule counts

Job Management (2 tools)

Tool	Description
k8s_get_jobs	List Jobs with completion status and timing
k8s_get_cronjobs	List CronJobs with schedule, suspend status, and last run

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.