mcp-k8s

# mcp-k8s [](https://github.com/silenceper/mcp-k8s/blob/main/go.mod) [](https://github.com/silenceper/mcp-k8s/blob/main/LICENSE) [](https://github.com/silenceper/mcp-k8s/releases) [](https://goreportcard.com/report/github.com/silenceper/mcp-k8s) [](https://github.com/silenceper/mcp-k8s/actions/workflows/go-ci.yml) [](https://github.com/silenceper/mcp-k8s/pulls) A Kubernetes MCP (Model Control Protocol) server that enables interaction with Kubernetes clusters through MCP tools. ## Features - Query supported Kubernetes resource types (built-in resources and CRDs) - Kubernetes resource operations with fine-grained control - Read operations: get resource details, list resources by type with filtering options - Write operations: create, update, and delete resources (each can be independently enabled/disabled) - Support for all Kubernetes resource types, including custom resources - Connects to Kubernetes cluster using kubeconfig - Helm support with fine-grained control - Helm releases management (list, get, install, upgrade, uninstall) - Helm repositories management (list, add, remove) - Each operation can be independently enabled/disabled ## Preview > Interaction through cursor  ## Use Cases ### 1. Kubernetes Resource Management via LLM - **Interactive Resource Management**: Manage Kubernetes resources through natural language interaction with LLM, eliminating the need to memorize complex kubectl commands - **Batch Operations**: Describe complex batch operation requirements in natural language, letting LLM translate them into specific resource operations - **Resource Status Queries**: Query cluster resource status using natural language and receive easy-to-understand responses ### 2. Automated Operations Scenarios - **Intelligent Operations Assistant**: Serve as an intelligent assistant for operators in daily cluster management tasks - **Problem Diagnosis**: Assist in cluster problem diagnosis through natural language problem descriptions - **Configuration Review**: Leverage LLM's understanding capabilities to help review and optimize Kubernetes resource configurations ### 3. Development and Testing Support - **Quick Prototype Validation**: Developers can quickly create and validate resource configurations through natural language - **Environment Management**: Simplify test environment resource management, quickly create, modify, and clean up test resources - **Configuration Generation**: Automatically generate resource configurations that follow best practices based on requirement descriptions ### 4. Education and Training Scenarios - **Interactive Learning**: Newcomers can learn Kubernetes concepts and operations through natural language interaction - **Best Practice Guidance**: LLM provides best practice suggestions during resource operations - **Error Explanation**: Provide easy-to-understand error explanations and correction suggestions when operations fail ## Architecture ### 1. Project Overview An stdio-based MCP server that connects to Kubernetes clusters and provides the following capabilities: - Query Kubernetes resource types (including built-in resources and CRDs) - CRUD operations on Kubernetes resources (with configurable write operations) - Helm operations for release and repository management ### 2. Technical Stack - Go - [mcp-go](https://github.com/mark3labs/mcp-go) SDK - Kubernetes client-go library - Helm v3 client library - Stdio for communication ### 3. Core Components 1. **MCP Server**: Uses mcp-go's `mcp-k8s` package to create an stdio-based MCP server 2. **K8s Client**: Uses client-go to connect to Kubernetes clusters 3. **Helm Client**: Uses Helm v3 library for Helm operations 4. **Tool Implementations**: Implements various MCP tools for different Kubernetes operations ### 4. Available Tools #### Resource Type Query Tools - `get_api_resources`: Get all supported API resource types in the cluster #### Resource Operation Tools - `get_resource`: Get detailed information about a specific resource - `list_resources`: List all instances of a resource type - `create_resource`: Create new resources (can be disabled) - `update_resource`: Update existing resources (can be disabled) - `delete_resource`: Delete resources (can be disabled) #### Helm Operation Tools - `list_helm_releases`: List all Helm releases in the cluster - `get_helm_release`: Get detailed information about a specific Helm release - `install_helm_chart`: Install a Helm chart (can be disabled) - `upgrade_helm_chart`: Upgrade a Helm release (can be disabled) - `uninstall_helm_chart`: Uninstall a Helm release (can be disabled) - `list_helm_repositories`: List configured Helm repositories - `add_helm_repository`: Add a new Helm repository (can be disabled) - `remove_helm_repository`: Remove a Helm repository (can be disabled) ## Usage mcp-k8s supports three communication modes: ### 1. Stdio Mode (Default) In stdio mode, mcp-k8s communicates with the client through standard input/output streams. This is the default mode and is suitable for most use cases. ```bash # Run in stdio mode (default) { "mcpServers": { "mcp-k8s": { "command": "/path/to/mcp-k8s", "args": [ "--kubeconfig", "/path/to/kubeconfig", "--enable-create", "--enable-delete", "--enable-update", "--enable-list", "--enable-helm-install", "--enable-helm-upgrade" ] } } } ``` ### 2. SSE Mode In SSE (Server-Sent Events) mode, mcp-k8s exposes an HTTP endpoint to mcp client. You can deploy the service on a remote server (but you need to pay attention to security) ```bash # Run in SSE mode ./bin/mcp-k8s --kubeconfig=/path/to/kubeconfig --transport=sse --port=8080 --host=localhost --enable-create --enable-delete --enable-list --enable-update --enable-helm-install # This command will open all operations ``` mcp config ```json { "mcpServers": { "mcp-k8s": { "url": "http://localhost:8080/sse", "args": [] } } } ``` SSE mode configuration: - `--transport`: Set to "sse" to enable SSE mode - `--port`: HTTP server port (default: 8080) - `--host`: HTTP server host (default: "localhost") ### 3. Streamable HTTP Mode In Streamable HTTP mode, mcp-k8s exposes an HTTP endpoint that supports both direct HTTP responses and SSE streams. This mode provides better flexibility and supports streaming output. ```bash # Run in Streamable HTTP mode ./bin/mcp-k8s --kubeconfig=/path/to/kubeconfig --transport=streamable-http --port=8080 --host=localhost --endpoint-path=/mcp --enable-create --enable-delete --enable-list --enable-update --enable-helm-install ``` mcp config ```json { "mcpServers": { "mcp-k8s": { "url": "http://localhost:8080/mcp", "args": [] } } } ``` Streamable HTTP mode configuration: - `--transport`: Set to "streamable-http" to enable Streamable HTTP mode - `--port`: HTTP server port (default: 8080) - `--host`: HTTP server host (default: "localhost") - `--endpoint-path`: Endpoint path for the MCP server (default: "/mcp") ### 4. Docker environment #### SSE Mode 1. Complete Example Assuming your image name is mcp-k8s and you need to map ports and set environment parameters, you can run: ```bash docker run --rm -p 8080:8080 -i -v ~/.kube/config:/root/.kube/config ghcr.io/silenceper/mcp-k8s:latest --transport=sse ``` #### Streamable HTTP Mode ```bash docker run --rm -p 8080:8080 -i -v ~/.kube/config:/root/.kube/config ghcr.io/silenceper/mcp-k8s:latest --transport=streamable-http --endpoint-path=/mcp ``` #### stdio Mode ```json { "mcpServers": { "mcp-k8s": { "command": "docker", "args": [ "run", "-i", "-v", "~/.kube/config:/root/.kube/config", "--rm", "ghcr.io/silenceper/mcp-k8s:latest" ] } } } ``` ## Getting Started ### Direct Usage You can directly download the binary for your platform from the [releases page](https://github.com/silenceper/mcp-k8s/releases) and use it immediately. ### Go Install ```bash go install github.com/silenceper/mcp-k8s/cmd/mcp-k8s@latest ``` ### Build #### Using Makefile (Recommended) The Makefile automatically injects version information from the VERSION file: ```bash git clone https://github.com/silenceper/mcp-k8s.git cd mcp-k8s make build ``` This will build with version information injected via ldflags. #### Direct Build ```bash git clone https://github.com/silenceper/mcp-k8s.git cd mcp-k8s go build -o bin/mcp-k8s cmd/mcp-k8s/main.go ``` Note: Direct build will show version as "dev" unless you specify ldflags manually. ### Command Line Arguments You can use `mcp-k8s --help` to see all available options, or `mcp-k8s --version` to check the version. #### Kubernetes Resource Operations - `--kubeconfig`: Path to Kubernetes configuration file (uses default config if not specified) - `--enable-create`: Enable resource creation operations (default: false) - `--enable-update`: Enable resource update operations (default: false) - `--enable-delete`: Enable resource deletion operations (default: false) - `--enable-list`: Enable resource list operations (default: true) #### Helm Operations - `--enable-helm-release-list`: Enable Helm release list operations (default: true) - `--enable-helm-release-get`: Enable Helm release get operations (default: true) - `--enable-helm-install`: Enable Helm chart installation (default: false) - `--enable-helm-upgrade`: Enable Helm chart upgrade (default: false) - `--enable-helm-uninstall`: Enable Helm chart uninstallation (default: false) - `--enable-helm-repo-list`: Enable Helm repository list operations (default: true) - `--enable-helm-repo-add`: Enable Helm repository add operations (default: false) - `--enable-helm-repo-remove`: Enable Helm repository remove operations (default: false) #### Transport Configuration - `--transport`: Transport type (stdio, sse, or streamable-http) (default: "stdio") - `--host`: Host for HTTP transport (SSE or Streamable HTTP) (default: "localhost") - `--port`: TCP port for HTTP transport (SSE or Streamable HTTP) (default: 8080) - `--endpoint-path`: Endpoint path for Streamable HTTP transport (default: "/mcp") #### Version Information - `--version`: Display version information including version, commit hash, and build date - `--help` or `-h`: Display help information ### Testing Streamable HTTP To test if Streamable HTTP mode is working correctly, you can use the provided test script: ```bash # Start the server in one terminal ./bin/mcp-k8s --transport=streamable-http --port=8080 --enable-list # In another terminal, run the test script ./test_streamable_http.sh ``` For detailed testing instructions, see [TEST_STREAMABLE_HTTP.md](./TEST_STREAMABLE_HTTP.md). ### Integration with MCP Clients mcp-k8s is an stdio-based MCP server that can be integrated with any MCP-compatible LLM client. Refer to your MCP client's documentation for integration instructions. ## Security Considerations - Write operations are strictly controlled through independent configuration switches - Uses RBAC to ensure K8s client has only necessary permissions - Validates all user inputs to prevent injection attacks - Helm operations follow the same security principles with read operations enabled by default and write operations disabled by default ## Follow WeChat Official Account