KubeSphere MCP Server

What is KubeSphere MCP Server?

The KubeSphere MCP Server is a Model Context Protocol (MCP) server that integrates with KubeSphere APIs, enabling AI agents to retrieve resources from KubeSphere. It provides four tool modules: Workspace Management, Cluster Management, User and Roles, and Extensions Center.

How to use KubeSphere MCP Server?

You need a KubeSphere cluster with an access address, username, and password. First generate a KSConfig file (YAML format, similar to kubeconfig) containing cluster connection details. Then obtain the ks-mcp-server binary by building from source (go build -o ks-mcp-server cmd/main.go) or downloading from GitHub releases. Finally, configure the MCP server in your AI agent (e.g., Claude Desktop or Cursor) using the stdio transport, specifying the --ksconfig path and optionally --ks-apiserver for HTTP access.

Key features of KubeSphere MCP Server

• Integrates KubeSphere APIs via the Model Context Protocol.
• Provides four dedicated tool modules for resource management.
• Uses a KSConfig file similar to kubeconfig for authentication.
• Supports both HTTPS and HTTP connections (HTTPS required by default).
• Allows optional base64-encoded CA certificates for HTTPS.
• Available as a standalone Go binary or prebuilt release artifact.

Use cases of KubeSphere MCP Server

• Query workspace resources and configurations from an AI assistant.
• Manage clusters and their metadata within a KubeSphere environment.
• Retrieve user and role information for access control auditing.
• Explore and interact with the KubeSphere Extensions Center.

FAQ from KubeSphere MCP Server

What are the prerequisites for using KubeSphere MCP Server?

You must have a running KubeSphere cluster and know its access address, a valid username, and password.

How do I create the KSConfig file?

The KSConfig is a YAML file with apiVersion, clusters, contexts, current-context, kind, preferences, and users fields. The default context name is kubesphere (can be overridden with KUBESPHERE_CONTEXT environment variable). You must provide the server address (HTTPS) and user credentials; the CA certificate field is optional.

Can I use HTTP instead of HTTPS?

Yes. In the KSConfig, set an arbitrary HTTPS address, then pass the actual HTTP address via the --ks-apiserver argument when running the server (e.g., --ks-apiserver http://172.10.0.1:30880).

How do I obtain the ks-mcp-server binary?

Either build it with go build -o ks-mcp-server cmd/main.go or download a precompiled release from the GitHub releases page, then place it in your $PATH.

How do I configure KubeSphere MCP Server in an AI agent?

Add an entry to your agent’s MCP configuration (e.g., Claude Desktop’s claude_desktop_config.json) with command: "ks-mcp-server" and args including stdio, --ksconfig <absolute path>, and optionally --ks-apiserver <address>. The agent will then communicate via stdio.