KubeSphere MCP Server: Workspace, Cluster, Users & Roles

Overview

KubeSphere MCP Server implements a Model Context Protocol (MCP) endpoint for KubeSphere: a small HTTP service that exposes workspace, cluster, user and role metadata from a KubeSphere/Kubernetes environment. The MCP server is intended to be used as a context provider for tooling that needs structured cluster information — for example, AI assistants, policy engines, dashboards or synchronizers.

By centralizing workspace, cluster, user and role information and offering a stable API, the MCP server makes it easy to plug KubeSphere state into downstream systems. It also integrates with the Extensions Center so you can add custom context providers or enrichments without changing the core service.

GitHub: https://github.com/kubesphere/ks-mcp-server

Features

• Exposes workspace, cluster, user and role metadata via simple HTTP API
• Designed to run inside or outside the cluster (uses kubeconfig or in-cluster config)
• Extensible via Extensions Center to add custom context sources or processors
• Lightweight Go-based binary that can be run as a container
• Token- or kubeconfig-based authentication to the Kubernetes API
• Provides discoverable endpoints for integration with assistants or automation tools

Installation / Configuration

Prerequisites:

• Go 1.18+ (if building locally) or Docker (to run the container)
• Access to a Kubernetes cluster (kubeconfig or in-cluster service account)
• kubectl (optional, for deploying manifests)

Clone and build locally:

git clone https://github.com/kubesphere/ks-mcp-server.git
cd ks-mcp-server
# build binary
go build -o ks-mcp-server ./cmd/ks-mcp-server
# run with kubeconfig
./ks-mcp-server --kubeconfig=$HOME/.kube/config --listen-address=":8080"

Run with Docker:

# build image
docker build -t ks-mcp-server:latest .
# run (mount kubeconfig if running outside cluster)
docker run -v $HOME/.kube/config:/root/.kube/config:ro -p 8080:8080 \
  -e KUBECONFIG=/root/.kube/config \
  ks-mcp-server:latest --listen-address=":8080"

Sample CLI flags / config (example):

# config.yaml
listenAddress: ":8080"
kubeconfig: "/root/.kube/config"    # optional, use in-cluster config when omitted
extensionsCenterURL: "https://extensions.example.com"
logLevel: "info"

Run using config file:

./ks-mcp-server --config=config.yaml

Deploy to Kubernetes (example manifest snippet):

apiVersion: apps/v1
kind: Deployment
metadata:
  name: ks-mcp-server
spec:
  selector:
    matchLabels:
      app: ks-mcp-server
  replicas: 1
  template:
    metadata:
      labels:
        app: ks-mcp-server
    spec:
      serviceAccountName: ks-mcp-server
      containers:
      - name: ks-mcp-server
        image: yourregistry/ks-mcp-server:latest
        args:
        - --listen-address=:8080
        - --extensions-center-url=https://extensions.example.com
        ports:
        - containerPort: 8080

Available Resources

Common HTTP endpoints (examples — adapt to your deployment address and version):

Notes:

• The exact routes and payload shapes are defined in the repo’s API definitions / OpenAPI schema; check the repository for up-to-date specs.
• Authentication between the MCP server and the Kubernetes API uses kubeconfig or in-cluster credentials.

Other resources:

• Extensions Center integration endpoint (configurable) to discover and load external context providers
• GitHub issues and docs: https://github.com/kubesphere/ks-mcp-server

Use Cases

1. Provide context to an AI assistant inside KubeSphere

   • An AI assistant calls /v1/workspaces and /v1/roles to craft recommendations that respect workspace boundaries and RBAC.
   • Example: assistant fetches user roles before suggesting cluster-scoped operations.

2. Audit and reporting

   • Periodically pull /v1/users and /v1/roles to generate access matrices. Combine with Prometheus or audit logs to correlate actions with role assignments.

3. Multi-cluster dashboard

   • A dashboard aggregates clusters by calling /v1/clusters. The MCP server normalizes cluster registration metadata and makes it easy to show health and ownership per workspace.

4. Enrichment via Extensions Center

   • Add an extension that queries an external CMDB and enriches workspace metadata (labels, owners). The MCP server loads the extension at runtime and includes enriched fields in /v1/workspaces responses.

Concrete curl example (local run on port 8080):

# list workspaces
curl http://localhost:8080/v1/workspaces

# get a specific role
curl http://localhost:8080/v1/roles/admin

Tips for Developers

• Start by running the server locally with your kubeconfig to inspect API responses and iterate quickly.
• Use the Extensions Center to add or prototype enrichment logic without modifying core code.
• Cache or rate-limit calls from downstream consumers if you intend to poll the MCP server frequently.
• Check the repository for OpenAPI or protobuf definitions to generate client bindings for your language.

For code, issues and latest docs: https://github.com/kubesphere/ks-mcp-server