MCP K8s Go

1<h4 align="center">Golang-based MCP server connecting to Kubernetes</h4>
2
3<h1 align="center">
4   <img src="docs/images/logo.png" width="180"/>
5   <br/>
6   MCP K8S Go
7</h1>
8
9<p align="center">
10  <a href="#features">Features</a> ⚙
11  <a href="#browse-with-inspector">Browse With Inspector</a> ⚙
12  <a href="#use-with-claude">Use With Claude</a> ⚙
13  <a href="https://github.com/strowk/mcp-k8s-go/blob/main/CONTRIBUTING.md">Contributing ↗</a> ⚙
14  <a href="https://modelcontextprotocol.io">About MCP ↗</a>
15</p>
16
17<p align="center">
18    <a href="https://github.com/strowk/mcp-k8s-go/actions/workflows/dependabot/dependabot-updates"><img src="https://github.com/strowk/mcp-k8s-go/actions/workflows/dependabot/dependabot-updates/badge.svg"></a>
19    <a href="https://github.com/strowk/mcp-k8s-go/actions/workflows/test.yaml"><img src="https://github.com/strowk/mcp-k8s-go/actions/workflows/test.yaml/badge.svg"></a>
20	  <a href="https://github.com/strowk/mcp-k8s-go/actions/workflows/golangci-lint.yaml"><img src="https://github.com/strowk/mcp-k8s-go/actions/workflows/golangci-lint.yaml/badge.svg"/></a>
21    <br/>
22    <a href="https://github.com/strowk/mcp-k8s-go/releases/latest"><img src="https://img.shields.io/github/v/release/strowk/mcp-k8s-go?logo=github&color=22ff22" alt="latest release badge"></a>
23    <a href="https://goreportcard.com/report/github.com/strowk/mcp-k8s-go"><img src="https://goreportcard.com/badge/github.com/strowk/mcp-k8s-go" alt="Go Reference"></a>
24    <a href="https://github.com/strowk/mcp-k8s-go/blob/main/LICENSE"><img src="https://img.shields.io/github/license/strowk/mcp-k8s-go" alt="license badge"></a>
25</p>
26
27## Features
28
29MCP 💬 prompt 🗂️ resource 🤖 tool 
30
31- 🗂️🤖 List Kubernetes contexts
32- 💬🤖 List Kubernetes namespaces
33- 🤖 List, get, create and modify any Kubernetes resources
34  - includes custom mappings for resources like pods, services, deployments
35- 🤖 List Kubernetes nodes
36- 💬 List Kubernetes pods
37- 🤖 Get Kubernetes events
38- 🤖 Get Kubernetes pod logs
39- 🤖 Run command in Kubernetes pod
40
41## Browse With Inspector
42
43To use latest published version with Inspector you can run this:
44
45```bash
46npx @modelcontextprotocol/inspector npx @strowk/mcp-k8s
47```
48
49## Use With Claude
50
51<details><summary><b>
52Demo Usage
53</b></summary>
54
55Following chat with Claude Desktop demonstrates how it looks when selected particular context as a resource and then asked to check pod logs for errors in kube-system namespace:
56
57![Claude Desktop](docs/images/claude-desktop-logs.png)
58
59</details>
60
61To use this MCP server with Claude Desktop (or any other client) you might need to choose which way of installation to use.
62
63You have multiple options:
64
65|              | <a href="#using-smithery">Smithery</a> | <a href="#using-mcp-get">mcp-get</a> | <a href="#prebuilt-from-npm">Pre-built NPM</a> | <a href="#from-github-releases">Pre-built in Github</a> | <a href="#building-from-source">From sources</a> | <a href="#using-docker">Using Docker</a> |
66| ------------ | -------------------------------------- | ------------------------------------ | ---------------------------------------------- | ------------------------------------------------------- | ------------------------------------------------ | ---------------------------------------- |
67| Claude Setup | Auto                                   | Auto                                 | Manual                                         | Manual                                                  | Manual                                           | Manual                                   |
68| Prerequisite | Node.js                                | Node.js                              | Node.js                                        | None                                                    | Golang                                           | Docker                                   |
69
70### Using Smithery
71
72To install MCP K8S Go for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@strowk/mcp-k8s):
73
74```bash
75npx -y @smithery/cli install @strowk/mcp-k8s --client claude
76```
77
78### Using mcp-get
79
80To install MCP K8S Go for Claude Desktop automatically via [mcp-get](https://mcp-get.com/packages/%40strowk%2Fmcp-k8s):
81
82```bash
83npx @michaellatman/mcp-get@latest install @strowk/mcp-k8s
84```
85
86### Manually with prebuilt binaries
87
88#### Prebuilt from npm
89
90Use this if you have npm installed and want to use pre-built binaries:
91
92```bash
93npm install -g @strowk/mcp-k8s
94```
95
96Then check version by running `mcp-k8s --version` and if this printed installed version, you can proceed to add configuration to `claude_desktop_config.json` file:
97
98```json
99{
100  "mcpServers": {
101    "mcp_k8s": {
102      "command": "mcp-k8s",
103      "args": []
104    }
105  }
106}
107```
108
109, or using `npx` with any client:
110
111```bash
112npx @strowk/mcp-k8s
113```
114
115For example for Claude:
116
117```json
118{
119  "mcpServers": {
120    "mcp_k8s": {
121      "command": "npx",
122      "args": [
123        "@strowk/mcp-k8s"
124      ]
125    }
126  }
127}
128```
129
130#### From GitHub releases
131
132Head to [GitHub releases](https://github.com/strowk/mcp-k8s-go/releases) and download the latest release for your platform.
133
134Unpack the archive, which would contain binary named `mcp-k8s-go`, put that binary somewhere in your PATH and then add the following configuration to the `claude_desktop_config.json` file:
135
136```json
137{
138  "mcpServers": {
139    "mcp_k8s": {
140      "command": "mcp-k8s-go",
141      "args": []
142    }
143  }
144}
145```
146
147### Building from source
148
149You would need Golang installed to build this project:
150
151```bash
152go get github.com/strowk/mcp-k8s-go
153go install github.com/strowk/mcp-k8s-go
154```
155
156, and then add the following configuration to the `claude_desktop_config.json` file:
157
158```json
159{
160  "mcpServers": {
161    "mcp_k8s_go": {
162      "command": "mcp-k8s-go",
163      "args": []
164    }
165  }
166}
167```
168
169### Using Docker
170
171This server is built and published to Docker Hub since 0.3.1-beta.2 release with multi-arch images available for linux/amd64 and linux/arm64 architectures.
172
173You can use latest tag f.e like this:
174
175```bash
176docker run -i -v ~/.kube/config:/home/nonroot/.kube/config --rm mcpk8s/server:latest
177```
178
179Windows users might need to replace `~/.kube/config` with `//c/Users/<username>/.kube/config` at least in Git Bash.
180
181For Claude:
182
183```json
184{
185  "mcpServers": {
186    "mcp_k8s_go": {
187      "command": "docker",
188      "args": [
189        "run",
190        "-i",
191        "-v",
192        "~/.kube/config:/home/nonroot/.kube/config",
193        "--rm",
194        "mcpk8s/server:latest"
195      ]
196    }
197  }
198}
199```
200
201### Environment Variables and Command-line Options
202
203The following environment variables are used by the MCP server:
204
205- `KUBECONFIG`: Path to your Kubernetes configuration file (optional, defaults to ~/.kube/config)
206
207The following command-line options are supported:
208
209- `--allowed-contexts=<ctx1,ctx2,...>`: Comma-separated list of allowed Kubernetes contexts that users can access. If not specified, all contexts are allowed.
210- `--readonly`: Disables any tool which can write changes to the cluster
211- `--help`: Display help information
212- `--version`: Display version information
213- `--mask-secrets`: Mask secrets in the output (default: true). Use `--mask-secrets=false` to disable masking
214
215For example if you are configuring Claude Desktop, you can add the following configuration to `claude_desktop_config.json` file:
216
217```json
218{
219    "mcpServers": {
220        "mcp_k8s": {
221            "command": "mcp-k8s",
222            "args": [
223                "--allowed-contexts=dev,prod",
224                "--readonly"
225            ]
226        }
227    }
228}
229```
230
231, which would allow only `dev` and `prod` contexts to be used and would disable any tool which can write changes to the cluster.
232
233