You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This Agents.md file provides comprehensive guidance for AI assistants and coding agents (like Claude, Gemini, Cursor, and others) to work with this codebase.
4
+
5
+
This repository contains the kubernetes-mcp-server project,
6
+
a powerful Go-based Model Context Protocol (MCP) server that provides native Kubernetes and OpenShift cluster management capabilities without external dependencies.
7
+
This MCP server enables AI assistants (like Claude, Gemini, Cursor, and others) to interact with Kubernetes clusters using the Model Context Protocol (MCP).
8
+
9
+
## Project Structure and Repository layout
10
+
11
+
- Go package layout follows the standard Go conventions:
12
+
-`cmd/kubernetes-mcp-server/` – main application entry point using Cobra CLI framework.
13
+
-`pkg/` – libraries grouped by domain.
14
+
-`config/` – configuration management.
15
+
-`helm/` - Helm chart operations integration.
16
+
-`http/` - HTTP server and authorization middleware.
17
+
-`kubernetes/` - Kubernetes client management, authentication, and access control.
18
+
-`mcp/` - Model Context Protocol (MCP) server implementation with tool registration and STDIO/HTTP support.
-`npm/` – Node packages that wraps the compiled binaries for distribution through npmjs.com.
23
+
-`python/` – Python package providing a script that downloads the correct platform binary from the GitHub releases page and runs it for distribution through pypi.org.
24
+
-`Dockerfile` - container image description file to distribute the server as a container image.
25
+
-`Makefile` – tasks for building, formatting, linting and testing.
26
+
27
+
## Feature development
28
+
29
+
Implement new functionality in the Go sources under `cmd/` and `pkg/`.
30
+
The JavaScript (`npm/`) and Python (`python/`) directories only wrap the compiled binary for distribution (npm and PyPI).
31
+
Most changes will not require touching them unless the version or packaging needs to be updated.
32
+
33
+
## Building
34
+
35
+
Use the provided Makefile targets:
36
+
37
+
```bash
38
+
# Format source and build the binary
39
+
make build
40
+
41
+
# Build for all supported platforms
42
+
make build-all-platforms
43
+
```
44
+
45
+
`make build` will run `go fmt` and `go mod tidy` before compiling.
46
+
The resulting executable is `kubernetes-mcp-server`.
To run the server locally, you can use `npx`, `uvx` or execute the binary directly:
59
+
60
+
```bash
61
+
# Using npx (Node.js package runner)
62
+
npx -y kubernetes-mcp-server@latest
63
+
64
+
# Using uvx (Python package runner)
65
+
uvx kubernetes-mcp-server@latest
66
+
67
+
# Binary execution
68
+
./kubernetes-mcp-server
69
+
```
70
+
71
+
This MCP server is designed to run both locally and remotely.
72
+
73
+
### Local Execution
74
+
75
+
When running locally, the server connects to a Kubernetes or OpenShift cluster using the kubeconfig file.
76
+
It reads the kubeconfig from the `--kubeconfig` flag, the `KUBECONFIG` environment variable, or defaults to `~/.kube/config`.
77
+
78
+
This means that `npx -y kubernetes-mcp-server@latest` on a workstation will talk to whatever cluster your current kubeconfig points to (e.g. a local Kind cluster).
79
+
80
+
### Remote Execution
81
+
82
+
When running remotely, the server can be deployed as a container image in a Kubernetes or OpenShift cluster.
83
+
The server can be run as a Deployment, StatefulSet, or any other Kubernetes resource that suits your needs.
84
+
The server will automatically use the in-cluster configuration to connect to the Kubernetes API server.
85
+
86
+
## Tests
87
+
88
+
Run all Go tests with:
89
+
90
+
```bash
91
+
make test
92
+
```
93
+
94
+
The test suite relies on the `setup-envtest` tooling from `sigs.k8s.io/controller-runtime`.
95
+
The first run downloads a Kubernetes `envtest` environment from the internet, so network access is required.
96
+
Without it some tests will fail during setup.
97
+
98
+
## Linting
99
+
100
+
Static analysis is performed with `golangci-lint`:
101
+
102
+
```bash
103
+
make lint
104
+
```
105
+
106
+
The `lint` target downloads the specified `golangci-lint` version if it is not already present under `_output/tools/bin/`.
107
+
108
+
## Dependencies
109
+
110
+
When introducing new modules run `make tidy` so that `go.mod` and `go.sum` remain tidy.
111
+
112
+
## Coding style
113
+
114
+
- Go modules target Go **1.24** (see `go.mod`).
115
+
- Tests are written with the standard library `testing` package.
116
+
- Build, test and lint steps are defined in the Makefile—keep them working.
117
+
118
+
## Distribution Methods
119
+
120
+
The server is distributed as a binary executable, a Docker image, an npm package, and a Python package.
121
+
122
+
-**Native binaries** for Linux, macOS, and Windows are available in the GitHub releases.
123
+
- A **container image** (Docker) is built and pushed to the `quay.io/manusa/kubernetes_mcp_server` repository.
124
+
- An **npm** package is available at [npmjs.com](https://www.npmjs.com/package/kubernetes-mcp-server).
125
+
It wraps the platform-specific binary and provides a convenient way to run the server using `npx`.
126
+
- A **Python** package is available at [pypi.org](https://pypi.org/project/kubernetes-mcp-server/).
127
+
It provides a script that downloads the correct platform binary from the GitHub releases page and runs it.
128
+
It provides a convenient way to run the server using `uvx` or `python -m kubernetes_mcp_server`.
Alternatively, you can install the extension manually by editing the `mcp.json` file:
100
+
101
+
```json
102
+
{
103
+
"mcpServers": {
104
+
"kubernetes-mcp-server": {
105
+
"command": "npx",
106
+
"args": ["-y", "kubernetes-mcp-server@latest"]
107
+
}
108
+
}
109
+
}
110
+
```
111
+
93
112
### Goose CLI
94
113
95
114
[Goose CLI](https://blog.marcnuri.com/goose-on-machine-ai-agent-cli-introduction) is the easiest (and cheapest) way to get rolling with artificial intelligence (AI) agents.
@@ -137,7 +156,7 @@ In this demo, I'll show you how to set up Kubernetes MCP server in VS code just
137
156
138
157
The Kubernetes MCP server can be configured using command line (CLI) arguments.
139
158
140
-
You can run the CLI executable either by using `npx`, `uvx`, or by downloading the [latest release binary](https://github.com/manusa/kubernetes-mcp-server/releases/latest).
159
+
You can run the CLI executable either by using `npx`, `uvx`, or by downloading the [latest release binary](https://github.com/containers/kubernetes-mcp-server/releases/latest).
141
160
142
161
```shell
143
162
# Run the Kubernetes MCP server using npx (in case you have npm and node installed)
0 commit comments