K8s Multicluster MCP Server

How to use

You interact with the MCP server through an MCP client to perform actions across multiple Kubernetes clusters. Start by placing all of your kubeconfig files into a single directory and pointing the server at that directory. Use the context parameter in your requests to target a specific cluster or namespace, and leverage cross-cluster commands to compare state, resources, and configurations across clusters. Common workflows include listing contexts, namespaces, and nodes across clusters, retrieving resource details from different contexts, and executing operations like scaling, applying configurations, or rolling back deployments across multiple clusters from one control plane.

When you issue a request, you can specify which cluster context to target, and the server will resolve it against the corresponding kubeconfig file. This enables centralized governance of dev, staging, and production environments without switching between multiple tooling setups.

How to install

Prerequisites you need before running the MCP server: Python 3.8 or higher, and the pip package manager. An optional uv package manager can speed up installation.

Install and run locally with the following concrete steps.

# Prerequisites check
python3 --version
pip --version

# Optional: install uv for faster installation
uv pip install -r requirements.txt
```

# Step 1: Obtain the code
git clone https://github.com/razvanmacovei/k8s-multicluster-mcp.git
cd k8s-multicluster-mcp

# Step 2: Create and activate a virtual environment
python3 -m venv .venv

# On Windows
.venv\Scripts\activate

# On macOS/Linux
source .venv/bin/activate

# Step 3: Install dependencies
pip install -r requirements.txt

# Step 4: Configure environment (point to kubeconfigs directory)
# This example uses an environment variable to locate kubeconfig files
export KUBECONFIG_DIR=/path/to/your/kubeconfigs

# Step 5: Run the application
python3 app.py

Configuration

Configure the MCP server to load multiple kubeconfig files from a single directory. The server runs a Python script and reads the kubeconfig directory from an environment variable.

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

Security and best practices

Keep kubeconfig files secure. Limit access to the kubeconfig directory and rotate credentials as needed. Use least privilege contexts when performing sensitive operations across clusters. Consider running the MCP server behind authentication and an internal firewall in production environments.

Examples and common scenarios

Multi-cluster context listing: Retrieve available kubecontexts across all kubeconfig files and compare resource counts between clusters.

Cross-cluster deployment status: Check rollout status and history for a deployment in prod and prod-like environments, then apply consistent changes across clusters.

Notes

Only the explicit MCP command and the kubeconfig directory path shown in the configuration are used to wire the server. Ensure your environment variable KUBECONFIG_DIR points to the directory containing all kubeconfig files for the clusters you want to manage.

k8s_get_contexts

List all available Kubernetes contexts across the loaded kubeconfig files.

k8s_get_namespaces

List all namespaces in a specified context.

k8s_get_nodes

List all nodes in a cluster.

k8s_get_resources

List resources of a specified kind within a context/namespace.

k8s_get_resource

Get detailed information about a specific resource.

k8s_get_pod_logs

Retrieve logs from a specific pod.

k8s_describe

Describe a resource with detailed information similar to kubectl describe.

k8s_apis

Discover available API groups and resources in the cluster.

k8s_crds

List Custom Resource Definitions in the cluster.

k8s_top_nodes

Display resource usage (CPU/memory) for nodes.

k8s_top_pods

Display resource usage (CPU/memory) for pods.

k8s_rollout_status

Get rollout status for a deployment/statefulset/daemonset.

k8s_rollout_history

Get revision history of a rollout.

k8s_rollout_undo

Undo a rollout to a previous revision.

k8s_rollout_restart

Restart a rollout.

k8s_rollout_pause

Pause a rollout.

k8s_rollout_resume

Resume a paused rollout.

k8s_scale_resource

Scale a deployment/statefulset/daemonset to a desired number of replicas.

k8s_autoscale_resource

Configure a Horizontal Pod Autoscaler for a resource.

k8s_update_resources

Update resource requests and limits for containers.

k8s_diagnose_application

Diagnose issues with an application across clusters.

k8s_create_resource

Create a Kubernetes resource from YAML/JSON content.

k8s_apply_resource

Apply a configuration to a resource (create or update).

k8s_patch_resource

Patch fields of a resource.

k8s_label_resource

Update labels on a resource.

k8s_annotate_resource

Update annotations on a resource.

k8s_expose_resource

Expose a resource as a new Kubernetes service.

k8s_set_resources_for_container

Set resource limits and requests for containers.

k8s_cordon_node

Mark a node as unschedulable.

k8s_uncordon_node

Mark a node as schedulable again.

k8s_drain_node

Drain a node in preparation for maintenance.

k8s_taint_node

Taint a node with scheduling constraints.

k8s_untaint_node

Remove taints from a node.

k8s_pod_exec

Execute a command in a container within a pod.