Skip to content
Back to search

mcp-k8s

A Kubernetes MCP (Model Control Protocol) server that enables interaction with Kubernetes clusters through MCP tools.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/silenceper--mcp-k8s/badge.svg)](/listings/silenceper--mcp-k8s)

HTML

<a href="/listings/silenceper--mcp-k8s"><img src="/api/listings/silenceper--mcp-k8s/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

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:

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

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:

# 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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 316 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # mcp-k8s
  2. [![Go Version](https://img.shields.io/github/go-mod/go-version/silenceper/mcp-k8s)](https://github.com/silenceper/mcp-k8s/blob/main/go.mod)
  3. [![License](https://img.shields.io/github/license/silenceper/mcp-k8s)](https://github.com/silenceper/mcp-k8s/blob/main/LICENSE)
  4. [![Latest Release](https://img.shields.io/github/v/release/silenceper/mcp-k8s)](https://github.com/silenceper/mcp-k8s/releases)
  5. [![Go Report Card](https://goreportcard.com/badge/github.com/silenceper/mcp-k8s)](https://goreportcard.com/report/github.com/silenceper/mcp-k8s)
  6. [![Go CI](https://github.com/silenceper/mcp-k8s/actions/workflows/go-ci.yml/badge.svg)](https://github.com/silenceper/mcp-k8s/actions/workflows/go-ci.yml)
  7. [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/silenceper/mcp-k8s/pulls)
  8. A Kubernetes MCP (Model Control Protocol) server that enables interaction with Kubernetes clusters through MCP tools.
  9. ## Features
  10. - Query supported Kubernetes resource types (built-in resources and CRDs)
  11. - Kubernetes resource operations with fine-grained control
  12. - Read operations: get resource details, list resources by type with filtering options
  13. - Write operations: create, update, and delete resources (each can be independently enabled/disabled)
  14. - Support for all Kubernetes resource types, including custom resources
  15. - Connects to Kubernetes cluster using kubeconfig
  16. - Helm support with fine-grained control
  17. - Helm releases management (list, get, install, upgrade, uninstall)
  18. - Helm repositories management (list, add, remove)
  19. - Each operation can be independently enabled/disabled
  20. ## Preview
  21. > Interaction through cursor
  22. ![](./docs/create-deployment.png)
  23. ## Use Cases
  24. ### 1. Kubernetes Resource Management via LLM
  25. - **Interactive Resource Management**: Manage Kubernetes resources through natural language interaction with LLM, eliminating the need to memorize complex kubectl commands
  26. - **Batch Operations**: Describe complex batch operation requirements in natural language, letting LLM translate them into specific resource operations
  27. - **Resource Status Queries**: Query cluster resource status using natural language and receive easy-to-understand responses
  28. ### 2. Automated Operations Scenarios
  29. - **Intelligent Operations Assistant**: Serve as an intelligent assistant for operators in daily cluster management tasks
  30. - **Problem Diagnosis**: Assist in cluster problem diagnosis through natural language problem descriptions
  31. - **Configuration Review**: Leverage LLM's understanding capabilities to help review and optimize Kubernetes resource configurations
  32. ### 3. Development and Testing Support
  33. - **Quick Prototype Validation**: Developers can quickly create and validate resource configurations through natural language
  34. - **Environment Management**: Simplify test environment resource management, quickly create, modify, and clean up test resources
  35. - **Configuration Generation**: Automatically generate resource configurations that follow best practices based on requirement descriptions
  36. ### 4. Education and Training Scenarios
  37. - **Interactive Learning**: Newcomers can learn Kubernetes concepts and operations through natural language interaction
  38. - **Best Practice Guidance**: LLM provides best practice suggestions during resource operations
  39. - **Error Explanation**: Provide easy-to-understand error explanations and correction suggestions when operations fail
  40. ## Architecture
  41. ### 1. Project Overview
  42. An stdio-based MCP server that connects to Kubernetes clusters and provides the following capabilities:
  43. - Query Kubernetes resource types (including built-in resources and CRDs)
  44. - CRUD operations on Kubernetes resources (with configurable write operations)
  45. - Helm operations for release and repository management
  46. ### 2. Technical Stack
  47. - Go
  48. - [mcp-go](https://github.com/mark3labs/mcp-go) SDK
  49. - Kubernetes client-go library
  50. - Helm v3 client library
  51. - Stdio for communication
  52. ### 3. Core Components
  53. 1. **MCP Server**: Uses mcp-go's `mcp-k8s` package to create an stdio-based MCP server
  54. 2. **K8s Client**: Uses client-go to connect to Kubernetes clusters
  55. 3. **Helm Client**: Uses Helm v3 library for Helm operations
  56. 4. **Tool Implementations**: Implements various MCP tools for different Kubernetes operations
  57. ### 4. Available Tools
  58. #### Resource Type Query Tools
  59. - `get_api_resources`: Get all supported API resource types in the cluster
  60. #### Resource Operation Tools
  61. - `get_resource`: Get detailed information about a specific resource
  62. - `list_resources`: List all instances of a resource type
  63. - `create_resource`: Create new resources (can be disabled)
  64. - `update_resource`: Update existing resources (can be disabled)
  65. - `delete_resource`: Delete resources (can be disabled)
  66. #### Helm Operation Tools
  67. - `list_helm_releases`: List all Helm releases in the cluster
  68. - `get_helm_release`: Get detailed information about a specific Helm release
  69. - `install_helm_chart`: Install a Helm chart (can be disabled)
  70. - `upgrade_helm_chart`: Upgrade a Helm release (can be disabled)
  71. - `uninstall_helm_chart`: Uninstall a Helm release (can be disabled)
  72. - `list_helm_repositories`: List configured Helm repositories
  73. - `add_helm_repository`: Add a new Helm repository (can be disabled)
  74. - `remove_helm_repository`: Remove a Helm repository (can be disabled)
  75. ## Usage
  76. mcp-k8s supports three communication modes:
  77. ### 1. Stdio Mode (Default)
  78. 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.
  79. ```bash
  80. # Run in stdio mode (default)
  81. {
  82. "mcpServers":
  83. {
  84. "mcp-k8s":
  85. {
  86. "command": "/path/to/mcp-k8s",
  87. "args":
  88. [
  89. "--kubeconfig",
  90. "/path/to/kubeconfig",
  91. "--enable-create",
  92. "--enable-delete",
  93. "--enable-update",
  94. "--enable-list",
  95. "--enable-helm-install",
  96. "--enable-helm-upgrade"
  97. ]
  98. }
  99. }
  100. }
  101. ```
  102. ### 2. SSE Mode
  103. In SSE (Server-Sent Events) mode, mcp-k8s exposes an HTTP endpoint to mcp client.
  104. You can deploy the service on a remote server (but you need to pay attention to security)
  105. ```bash
  106. # Run in SSE mode
  107. ./bin/mcp-k8s --kubeconfig=/path/to/kubeconfig --transport=sse --port=8080 --host=localhost --enable-create --enable-delete --enable-list --enable-update --enable-helm-install
  108. # This command will open all operations
  109. ```
  110. mcp config
  111. ```json
  112. {
  113. "mcpServers": {
  114. "mcp-k8s": {
  115. "url": "http://localhost:8080/sse",
  116. "args": []
  117. }
  118. }
  119. }
  120. ```
  121. SSE mode configuration:
  122. - `--transport`: Set to "sse" to enable SSE mode
  123. - `--port`: HTTP server port (default: 8080)
  124. - `--host`: HTTP server host (default: "localhost")
  125. ### 3. Streamable HTTP Mode
  126. 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.
  127. ```bash
  128. # Run in Streamable HTTP mode
  129. ./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
  130. ```
  131. mcp config
  132. ```json
  133. {
  134. "mcpServers": {
  135. "mcp-k8s": {
  136. "url": "http://localhost:8080/mcp",
  137. "args": []
  138. }
  139. }
  140. }
  141. ```
  142. Streamable HTTP mode configuration:
  143. - `--transport`: Set to "streamable-http" to enable Streamable HTTP mode
  144. - `--port`: HTTP server port (default: 8080)
  145. - `--host`: HTTP server host (default: "localhost")
  146. - `--endpoint-path`: Endpoint path for the MCP server (default: "/mcp")
  147. ### 4. Docker environment
  148. #### SSE Mode
  149. 1. Complete Example
  150. Assuming your image name is mcp-k8s and you need to map ports and set environment parameters, you can run:
  151. ```bash
  152. docker run --rm -p 8080:8080 -i -v ~/.kube/config:/root/.kube/config ghcr.io/silenceper/mcp-k8s:latest --transport=sse
  153. ```
  154. #### Streamable HTTP Mode
  155. ```bash
  156. 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
  157. ```
  158. #### stdio Mode
  159. ```json
  160. {
  161. "mcpServers": {
  162. "mcp-k8s": {
  163. "command": "docker",
  164. "args": [
  165. "run",
  166. "-i",
  167. "-v",
  168. "~/.kube/config:/root/.kube/config",
  169. "--rm",
  170. "ghcr.io/silenceper/mcp-k8s:latest"
  171. ]
  172. }
  173. }
  174. }
  175. ```
  176. ## Getting Started
  177. ### Direct Usage
  178. You can directly download the binary for your platform from the [releases page](https://github.com/silenceper/mcp-k8s/releases) and use it immediately.
  179. ### Go Install
  180. ```bash
  181. go install github.com/silenceper/mcp-k8s/cmd/mcp-k8s@latest
  182. ```
  183. ### Build
  184. #### Using Makefile (Recommended)
  185. The Makefile automatically injects version information from the VERSION file:
  186. ```bash
  187. git clone https://github.com/silenceper/mcp-k8s.git
  188. cd mcp-k8s
  189. make build
  190. ```
  191. This will build with version information injected via ldflags.
  192. #### Direct Build
  193. ```bash
  194. git clone https://github.com/silenceper/mcp-k8s.git
  195. cd mcp-k8s
  196. go build -o bin/mcp-k8s cmd/mcp-k8s/main.go
  197. ```
  198. Note: Direct build will show version as "dev" unless you specify ldflags manually.
  199. ### Command Line Arguments
  200. You can use `mcp-k8s --help` to see all available options, or `mcp-k8s --version` to check the version.
  201. #### Kubernetes Resource Operations
  202. - `--kubeconfig`: Path to Kubernetes configuration file (uses default config if not specified)
  203. - `--enable-create`: Enable resource creation operations (default: false)
  204. - `--enable-update`: Enable resource update operations (default: false)
  205. - `--enable-delete`: Enable resource deletion operations (default: false)
  206. - `--enable-list`: Enable resource list operations (default: true)
  207. #### Helm Operations
  208. - `--enable-helm-release-list`: Enable Helm release list operations (default: true)
  209. - `--enable-helm-release-get`: Enable Helm release get operations (default: true)
  210. - `--enable-helm-install`: Enable Helm chart installation (default: false)
  211. - `--enable-helm-upgrade`: Enable Helm chart upgrade (default: false)
  212. - `--enable-helm-uninstall`: Enable Helm chart uninstallation (default: false)
  213. - `--enable-helm-repo-list`: Enable Helm repository list operations (default: true)
  214. - `--enable-helm-repo-add`: Enable Helm repository add operations (default: false)
  215. - `--enable-helm-repo-remove`: Enable Helm repository remove operations (default: false)
  216. #### Transport Configuration
  217. - `--transport`: Transport type (stdio, sse, or streamable-http) (default: "stdio")
  218. - `--host`: Host for HTTP transport (SSE or Streamable HTTP) (default: "localhost")
  219. - `--port`: TCP port for HTTP transport (SSE or Streamable HTTP) (default: 8080)
  220. - `--endpoint-path`: Endpoint path for Streamable HTTP transport (default: "/mcp")
  221. #### Version Information
  222. - `--version`: Display version information including version, commit hash, and build date
  223. - `--help` or `-h`: Display help information
  224. ### Testing Streamable HTTP
  225. To test if Streamable HTTP mode is working correctly, you can use the provided test script:
  226. ```bash
  227. # Start the server in one terminal
  228. ./bin/mcp-k8s --transport=streamable-http --port=8080 --enable-list
  229. # In another terminal, run the test script
  230. ./test_streamable_http.sh
  231. ```
  232. For detailed testing instructions, see [TEST_STREAMABLE_HTTP.md](./TEST_STREAMABLE_HTTP.md).
  233. ### Integration with MCP Clients
  234. 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.
  235. ## Security Considerations
  236. - Write operations are strictly controlled through independent configuration switches
  237. - Uses RBAC to ensure K8s client has only necessary permissions
  238. - Validates all user inputs to prevent injection attacks
  239. - Helm operations follow the same security principles with read operations enabled by default and write operations disabled by default
  240. ## Follow WeChat Official Account
  241. ![AI技术小林](./docs/qrcode.png)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.