MCP Server for Kubernetes Multicluster Operations

Overview

This MCP (Model Context Protocol) server provides a lightweight HTTP API to manage multiple Kubernetes clusters from a single service. It reads multiple kubeconfig files and exposes a consistent, REST-like interface so you can perform common cluster operations — listing resources, applying manifests, running kubectl-like commands, and storing files — across one or many clusters at once.

The server is useful when you operate several clusters and want to centralize automation or provide a single control plane for CI/CD, auditing, or multi-cluster apps. Instead of scripting multiple kubectl invocations and handling kubeconfigs manually, the MCP server abstracts cluster access behind a predictable API and a simple configuration surface.

Features

• Load multiple kubeconfig files from a directory and treat each as a managed cluster.
• Standardized HTTP API for common operations: list clusters, get resources, apply manifests, run commands.
• Execute operations against a single cluster or broadcast to multiple clusters concurrently.
• File storage endpoint to upload/download manifests and artifacts associated with cluster operations.
• Lightweight, container-friendly deployment; can run as a single binary or Docker image.
• Simple configuration via environment variables or command-line flags.

Installation / Configuration

Build from source (Go required):

git clone https://github.com/razvanmacovei/k8s-multicluster-mcp.git
cd k8s-multicluster-mcp
go build -o mcp-server ./cmd/server
./mcp-server --kubeconfig-dir=/path/to/kubeconfigs --storage-dir=/var/lib/mcp

Run with Docker:

docker run -p 8080:8080 \
  -v /path/to/kubeconfigs:/kubeconfigs:ro \
  -v /path/to/storage:/mcp-storage \
  -e KUBECONFIG_DIR=/kubeconfigs \
  -e STORAGE_DIR=/mcp-storage \
  razvanmacovei/k8s-multicluster-mcp:latest

Common environment variables and flags:

Kubeconfig directory layout example:

/path/to/kubeconfigs/
  cluster-a.yaml
  cluster-b.yaml
  cluster-c.yaml

The server will read every file in the kubeconfig directory and register a cluster using the filename (without extension) as the cluster identifier.

Available Tools / Resources

The server exposes a small set of HTTP endpoints. Below are common ones; consult the server’s OpenAPI (if enabled) or README for the exact schema.

Example endpoints

• GET /clusters
  • List registered clusters and basic status
• GET /clusters/{name}/resources?kind=Deployment&namespace=default
  • Fetch resources of a given kind
• POST /clusters/{name}/apply
  • Apply a YAML manifest payload to a specific cluster
• POST /clusters/broadcast/apply
  • Apply a manifest to all or a subset of clusters
• POST /files/upload
  • Upload manifest or artifact to server storage
• GET /files/{id}
  • Download stored artifact

Example: list clusters

curl -s http://localhost:8080/clusters | jq

Example: apply a manifest to cluster-a

curl -X POST http://localhost:8080/clusters/cluster-a/apply \
  -H "Content-Type: application/yaml" \
  --data-binary "@nginx-deployment.yaml"

Example: broadcast apply (apply to all clusters)

curl -X POST http://localhost:8080/clusters/broadcast/apply \
  -H "Content-Type: application/yaml" \
  --data-binary "@global-config.yaml"

Authentication: For production use, run the service behind an API gateway or add authentication (HTTP basic, bearer tokens, or mTLS). The project focuses on cluster orchestration; secure exposure is your responsibility.

Use Cases

• Multi-cluster deployments: Apply the same manifest across development, staging, and production clusters with a single API call (broadcast apply).
• Inventory and auditing: Query and consolidate resource lists (Deployments, Pods, Services) from many clusters into a central dashboard or report.
• CI/CD orchestration: Integrate the MCP server into pipelines to run cluster operations without distributing kubeconfigs to CI runners. A pipeline job can upload a manifest and instruct the server to apply it to a target cluster.
• Backup and artifact storage: Upload generated manifests, Helm charts, or logs to the server’s storage endpoint tied to an operation for troubleshooting or audit trails.
• Controlled remote debugging: Execute read-only queries (get/logs) across clusters to trace issues without providing direct kubeconfig access to users.

Concrete example: rolling configuration change

1. Upload the new config file to /files/upload.
2. POST /clusters/broadcast/apply with a small patch manifest referencing the uploaded file.
3. Monitor rollout status by polling /clusters/{name}/resources?kind=Deployment&name=my-app until desired state.

Tips and Next Steps

• Keep kubeconfig files read-only and restrict who can write to the KUBECONFIG_DIR.
• Combine this server with a lightweight UI or a dashboard to visualize multi-cluster state.
• Add authentication and HTTPS before exposing the service outside a trusted network.
• For large fleets, paginate /clusters results or use label-based selection to target subsets.

This MCP server is a practical building block for multi-cluster workflows, letting you centralize routine cluster operations behind a simple, reusable API.