multicluster

This MCP server acts as a gateway that enables a Generative AI system to interact with multiple Kubernetes clusters via the Model Context Protocol (MCP). It leverages Open Cluster Management (OCM) style multi-cluster capabilities to retrieve resources from the hub (current context) and managed clusters, connect to a specific cluster using a ClusterRole, and access resources across multiple clusters for observability tasks such as metrics, logs, and alerts. The server is designed to work with kubectl-compatible contexts and relies on your local kubeconfig to resolve cluster credentials.

To use the server, configure it through the provided MCP configuration snippet, then start it using the npx command. The server will expose MCP endpoints that your GenAI agent can query to list, get, and observe Kubernetes resources across clusters. Ensure kubectl is installed and that your KUBECONFIG environment variable points to a kubeconfig that has access to the hub and managed clusters. In multi-cluster setups, the hub context serves as the control plane, with the server coordinating access to other clusters through that hub context.

Prerequisites:

• Node.js and npm installed
• kubectl installed
• Access to a kubeconfig with hub and managed clusters

Install and run:

1. Install Node.js from https://nodejs.org/ or your OS package manager.
2. Use npm to run the MCP server via npx (no global install required).

Example steps:

# 1) Ensure prerequisites
kubectl version --client
node -v
npm -v

# 2) Run the MCP server via npx (as shown in the configuration)
# This will fetch and run the multicluster-mcp-server package
npx -y multicluster-mcp-server@latest

Alternative explicit configuration example (as in the README):

cat << 'JSON' > mcp-config.json
{
  "mcpServers": {
    "multicluster-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "multicluster-mcp-server@latest"
      ]
    }
  }
}
JSON

# Then run using your preferred MCP runner that consumes the config

Notes:

• The MCP server depends on kubectl context and the KUBECONFIG environment variable for cluster access.

Tips and common issues:

• Ensure kubectl is installed and kubectl config is correctly set for hub and managed clusters.
• The server uses the hub cluster context by default; other clusters are accessed via this hub.
• If you encounter authentication errors, verify that your kubeconfig credentials are valid and that the necessary ClusterRoles/permissions are granted.
• You can customize the KUBECONFIG path via the KUBECONFIG environment variable if you manage multiple kubeconfig files.
• When running in CI, ensure the environment provides access to the kubeconfig and network connectivity to the clusters.
• If a newer MCP server package is published, you can upgrade by changing the version in the npx argument (e.g., multicluster-mcp-server@latest).

Environment variables:

• KUBECONFIG: Path to the kubeconfig file that contains hub and managed cluster contexts.

Configuration options:

• The mcpServers section allows multiple servers; here we configure multicluster-mcp-server. You can add more entries following the same structure.