ks

The KubeSphere MCP Server provides an MCP (Model Context Protocol) interface to interact with KubeSphere APIs. It exposes four tool modules: Workspace Management, Cluster Management, User and Roles, and Extensions Center, enabling MCP-enabled agents or clients to query and manage KubeSphere resources through the MCP protocol. To use it, run the ks-mcp-server binary (compiled from the repository) and point your MCP client configuration at it. The server expects a ksconfig configuration (similar to a kubeconfig) that contains the KubeSphere cluster access information, and optionally the cluster API address. You can integrate the server with clients like Claude Desktop or Cursor by providing an mcpServers entry that invokes ks-mcp-server with the necessary arguments, including the path to your ksconfig file and the KubeSphere API address if you’re using HTTP access. Once running, you can chat with the MCP server to manage workspaces, clusters, users/roles, and extensions through the MCP protocol without directly interacting with the KubeSphere UI.

Prerequisites:

• A KubeSphere cluster with access credentials (username and password).
• A supported environment for building or running the ks-mcp-server binary (Go toolchain if building from source).

Install steps:

1. Install Go (if building from source):
   • Follow the Go installation instructions for your OS: https://golang.org/doc/install
2. Build the ks-mcp-server binary from source:
   • git clone https://github.com/kubesphere/ks-mcp-server.git
   • cd ks-mcp-server
   • go build -o ks-mcp-server cmd/main.go
   • Ensure the binary is in your PATH (e.g., mv ks-mcp-server /usr/local/bin/).
3. Alternatively, download a prebuilt release binary from the repository releases page and place it in your PATH.
4. Prepare a KSConfig file (ksconfig) similar to kubeconfig as described in the README, including server address, credentials, and any CA data if HTTPS is used.
5. Verify prerequisites and environment:
   • Access to a KubeSphere cluster
   • KSConfig file prepared
   • If using HTTP, ensure the ks-apiserver address is provided as needed when configuring clients

Run the server:

• Ensure the ks-mcp-server binary is executable and accessible, then start it in the background or foreground as needed. Example: ./ks-mcp-server

Usage with clients (example):

• Provide the MCP configuration to the client (Claude Desktop, Cursor, etc.) with the ks-mcp-server command and the path to the ksconfig file via --ksconfig and the --ks-apiserver address if required by your setup.

Notes and tips:

• The KSConfig file format is YAML and mirrors kubeconfig structure, including clusters, contexts, and users. Fill in the server address, authentication details, and CA data if HTTPS is used.
• If you run KS behind HTTP, you may need to provide the HTTP-to-HTTPS adjustment via client parameters or server configuration as described in the README (for example, using --ks-apiserver http://<address>).
• The MCP server exposes multiple modules for workspace, cluster, user/roles, and extensions; use the MCP client to query or manage resources via standardized MCP requests.
• When integrating with Claude Desktop or Cursor, you typically create an mcpServers entry with the command ks-mcp-server and pass --ksconfig and --ks-apiserver as arguments. Ensure absolute path to ksconfig is provided.
• If you encounter connection or authentication issues, verify that the KSConfig’s server address is correct and that the credentials match the KubeSphere user configured with appropriate permissions.