Kubernetes Multi-Cluster MCP Server

A Model Context Protocol (MCP) server for managing multiple Kubernetes clusters. This server provides generic operations for any Kubernetes resource type, plus specialized operations for ServiceExports across multiple configured clusters.

Features

• Multi-cluster support with a single server instance
• Generic Resource Operations: Get and List any Kubernetes resource (pods, deployments, services, CRDs, etc.)
  • Supports both namespaced and cluster-scoped resources
  • Works with any API version (v1, apps/v1, custom CRDs, etc.)
  • Label selector support for filtering
• ServiceExports (multicluster.x-k8s.io/v1alpha1): Get, List, Create, Delete
  • Simplified creation with just name (manifest optional)
  • Full MCS API compatibility
• Namespace Operations: List namespaces across clusters
• Multiple transport modes:
  • Stdio: JSON-RPC 2.0 over stdin/stdout (default)
  • HTTP: RESTful HTTP server with JSON-RPC 2.0
• Easy configuration via YAML file
• CORS support for HTTP mode

Prerequisites

• Go 1.21 or later
• Access to one or more Kubernetes clusters
• Valid kubeconfig files for each cluster

Installation

Build from source

git clone https://github.com/vthapar/subm-mcp-server.git
cd subm-mcp-server
make build

The binary will be created at bin/subm-mcp-server.

Install

make install

Configuration

Create a configuration file config.yaml:

clusters:
  - name: cluster1
    kubeconfig: /path/to/cluster1/kubeconfig
    context: cluster1-context  # optional

  - name: cluster2
    kubeconfig: /path/to/cluster2/kubeconfig
    context: cluster2-context  # optional

  - name: local
    kubeconfig: ~/.kube/config

# Server configuration (optional)
server:
  transport: stdio  # "stdio" or "http", defaults to "stdio"
  http:
    host: localhost  # defaults to "localhost"
    port: 8080       # defaults to 8080

See config.yaml.example for a complete example.

Usage

Running the server

Stdio Mode (Default)

# Using -config flag
./bin/subm-mcp-server -config config.yaml

# Using environment variable
export MCP_K8S_CONFIG=config.yaml
./bin/subm-mcp-server

# Override transport mode via command line
./bin/subm-mcp-server -config config.yaml -transport stdio

The server reads JSON-RPC 2.0 requests from stdin and writes responses to stdout.

HTTP Mode

# Using config file with HTTP transport
./bin/subm-mcp-server -config config.yaml

# Override via command line flags
./bin/subm-mcp-server -config config.yaml -transport http

# Custom host and port
./bin/subm-mcp-server -config config.yaml -transport http -http-host 0.0.0.0 -http-port 9000

The HTTP server exposes the following endpoints:

• POST /mcp - MCP JSON-RPC 2.0 endpoint
• GET /health - Health check endpoint

Available Tools

Cluster Management

• list_clusters - List all configured clusters
• list_namespaces - List all namespaces in a cluster

Generic Resource Operations

• get_resource - Get any Kubernetes resource by API version and type
• list_resources - List any Kubernetes resources by API version and type

ServiceExports (Specialized Operations)

• get_serviceexport - Get a specific ServiceExport
• list_serviceexports - List ServiceExports in a namespace
• create_serviceexport - Create a new ServiceExport (simple name-based or full manifest)
• delete_serviceexport - Delete a ServiceExport

Tool Details

Generic Resource Operations

The get_resource and list_resources tools work with any Kubernetes resource type:

Supported Resource Types:

• Core resources: pods, services, configmaps, secrets, nodes, namespaces, etc. (use api_version: "v1")
• Apps resources: deployments, statefulsets, daemonsets, replicasets (use api_version: "apps/v1")
• Custom Resources: Any CRD installed in your cluster (e.g., api_version: "submariner.io/v1alpha1", `reso

... View full README on GitHub