Skip to content

Commit b457cc5

Browse files
matzewmatzew
committed
Adding inital README and instructions for setup of server with Kubernetes, as well as with 'claude code CLI'
Signed-off-by: Matthias Wessendorf <[email protected]>
1 parent e86686a commit b457cc5

File tree

3 files changed

+362
-0
lines changed

3 files changed

+362
-0
lines changed

‎docs/GETTING_STARTED_CLAUDE_CODE.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
# Using Kubernetes MCP Server with Claude Code CLI
2+
3+
This guide shows you how to configure the Kubernetes MCP Server with Claude Code CLI.
4+
5+
> **Prerequisites:** Complete the [Getting Started with Kubernetes](GETTING_STARTED_KUBERNETES.md) guide first to create a ServiceAccount and kubeconfig file.
6+
7+
## Quick Setup
8+
9+
Add the MCP server using the `claude mcp add-json` command:
10+
11+
```bash
12+
claude mcp add-json kubernetes-mcp-server \
13+
'{"command":"npx","args":["-y","kubernetes-mcp-server@latest","--read-only"],"env":{"KUBECONFIG":"'${HOME}'/.kube/mcp-viewer.kubeconfig"}}' \
14+
-s user
15+
```
16+
17+
**What this does:**
18+
- Adds the Kubernetes MCP Server to your Claude Code configuration
19+
- Uses `npx` to automatically download and run the latest version
20+
- Enables read-only mode for safety
21+
- Uses the kubeconfig file you created in the Getting Started guide
22+
- `-s user` makes it available in all your projects
23+
24+
## Manual Configuration (Alternative)
25+
26+
If you prefer to edit the config file manually:
27+
28+
**Location:** `~/.config/claude-code/config.toml`
29+
30+
```toml
31+
[[mcp_servers]]
32+
name = "kubernetes-mcp-server"
33+
command = "npx"
34+
args = [
35+
"-y",
36+
"kubernetes-mcp-server@latest",
37+
"--read-only"
38+
]
39+
40+
[mcp_servers.env]
41+
KUBECONFIG = "/home/YOUR_USERNAME/.kube/mcp-viewer.kubeconfig"
42+
```
43+
44+
**Important:** Replace `/home/YOUR_USERNAME/` with your actual home directory path.
45+
46+
## Verify Connection
47+
48+
After adding the MCP server, verify it's connected:
49+
50+
```bash
51+
claude mcp list
52+
```
53+
54+
Expected output:
55+
```
56+
Checking MCP server health...
57+
58+
kubernetes-mcp-server: npx -y kubernetes-mcp-server@latest --read-only - ✓ Connected
59+
```
60+
61+
## Using the MCP Server
62+
63+
Once connected, interact with your Kubernetes cluster using natural language:
64+
65+
```
66+
Show me all pods that are not in Running state
67+
```
68+
69+
```
70+
List all namespaces in my cluster
71+
```
72+
73+
```
74+
What nodes are in my cluster and what's their status?
75+
```
76+
77+
For queries like the above, Claude will use the Kubernetes MCP Server to fetch and display the relevant information from your cluster!
78+
79+
## Configuration Options
80+
81+
Common command-line flags you can add to the `args` array:
82+
83+
| Flag | Description | Example |
84+
|------|-------------|---------|
85+
| `--read-only` | Enable read-only mode (recommended) | Already included above |
86+
| `--kubeconfig <path>` | Path to kubeconfig file | Use `KUBECONFIG` env var instead |
87+
| `--context <name>` | Use specific context from kubeconfig | `"--context", "my-cluster"` |
88+
| `--namespace <ns>` | Default namespace for operations | `"--namespace", "production"` |
89+
90+
**Example with custom namespace:**
91+
92+
```bash
93+
claude mcp add-json kubernetes-mcp-server \
94+
'{"command":"npx","args":["-y","kubernetes-mcp-server@latest","--read-only","--namespace","production"],"env":{"KUBECONFIG":"'${HOME}'/.kube/mcp-viewer.kubeconfig"}}' \
95+
-s user
96+
```
97+
98+
## Next Steps
99+
100+
- Review the [Getting Started with Kubernetes](GETTING_STARTED_KUBERNETES.md) guide for more details on ServiceAccount setup
101+
- Explore the [main README](../README.md) for more MCP server capabilities

‎docs/GETTING_STARTED_KUBERNETES.md‎

Lines changed: 240 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,240 @@
1+
# Getting Started with Kubernetes MCP Server
2+
3+
This guide walks you through the foundational setup for using the Kubernetes MCP Server with your Kubernetes cluster. You'll create a dedicated, read-only ServiceAccount and generate a secure kubeconfig file that can be used with various MCP clients.
4+
5+
> **Note:** After completing this guide, continue with the [Claude Code CLI guide](GETTING_STARTED_CLAUDE_CODE.md). See the [docs README](README.md) for all available guides.
6+
7+
## What You'll Create
8+
9+
By the end of this guide, you'll have:
10+
- A dedicated `mcp-viewer` ServiceAccount with read-only cluster access
11+
- A secure, time-bound authentication token
12+
- A dedicated kubeconfig file (`~/.kube/mcp-viewer.kubeconfig`)
13+
14+
## Prerequisites
15+
16+
- A running Kubernetes cluster
17+
- `kubectl` CLI installed and configured
18+
- Cluster admin permissions to create ServiceAccounts and RBAC bindings
19+
20+
## 1. Create a Read-Only ServiceAccount and RBAC
21+
22+
A ServiceAccount represents a non-human identity. Binding it to a read-only role lets tools query the cluster safely without using administrator credentials.
23+
24+
### Step 1.1: Create the Namespace and ServiceAccount
25+
26+
First, create a Namespace for the ServiceAccount:
27+
28+
```bash
29+
# Create or pick a Namespace for the ServiceAccount
30+
kubectl create namespace mcp
31+
32+
# Create the ServiceAccount
33+
kubectl create serviceaccount mcp-viewer -n mcp
34+
```
35+
36+
### Step 1.2: Grant Read-Only Access (RBAC)
37+
38+
Use a ClusterRoleBinding or RoleBinding to grant read-only permissions.
39+
40+
#### Option A: Cluster-Wide Read-Only (Most Common)
41+
42+
This binds the ServiceAccount to the built-in `view` ClusterRole, which provides read-only access across the whole cluster.
43+
44+
```bash
45+
# Binds the view ClusterRole to the ServiceAccount
46+
kubectl create clusterrolebinding mcp-viewer-crb \
47+
--clusterrole=view \
48+
--serviceaccount=mcp:mcp-viewer
49+
```
50+
51+
#### Option B: Namespace-Scoped Only (Tighter Scope)
52+
53+
This limits read access to the `mcp` namespace only, using the built-in `view` Role.
54+
55+
```bash
56+
# Binds the view role to the ServiceAccount within the 'mcp' namespace
57+
kubectl create rolebinding mcp-viewer-rb \
58+
--role=view \
59+
--serviceaccount=mcp:mcp-viewer \
60+
-n mcp
61+
```
62+
63+
### Quick Verification (Optional)
64+
65+
Verify the permissions granted to the ServiceAccount:
66+
67+
```bash
68+
# Check if the ServiceAccount can list pods cluster-wide
69+
# Expect 'yes' if you used the view ClusterRole (Option A)
70+
kubectl auth can-i list pods --as=system:serviceaccount:mcp:mcp-viewer --all-namespaces
71+
```
72+
73+
## 2. Mint a ServiceAccount Token
74+
75+
Tools authenticate via a bearer token. We use the TokenRequest API (`kubectl create token`) to generate a secure, short-lived token.
76+
77+
```bash
78+
# Create a time-bound token (choose a duration, e.g., 2 hours)
79+
TOKEN="$(kubectl create token mcp-viewer --duration=2h -n mcp)"
80+
81+
# Verify the token was generated (Optional)
82+
echo "$TOKEN"
83+
```
84+
85+
**Note:** The `kubectl create token` command requires Kubernetes v1.24+. For older versions, you'll need to extract the token from the ServiceAccount's secret.
86+
87+
## 3. Build a Dedicated Kubeconfig
88+
89+
A dedicated kubeconfig file isolates this ServiceAccount's credentials from your personal admin credentials, making it easy to point external tools at.
90+
91+
### Step 3.1: Get Cluster Details
92+
93+
Get the API server address and certificate authority from your current active context:
94+
95+
```bash
96+
# 1. Get the current cluster API server address
97+
API_SERVER="$(kubectl config view --minify -o jsonpath='{.clusters[0].cluster.server}')"
98+
99+
# 2. Get the cluster's Certificate Authority (CA) file path or data
100+
# First, try to get the CA file path
101+
CA_FILE="$(kubectl config view --minify -o jsonpath='{.clusters[0].cluster.certificate-authority}')"
102+
103+
# If CA file is not set, extract the CA data and write it to a temp file
104+
if [ -z "$CA_FILE" ]; then
105+
CA_FILE="/tmp/k8s-ca-$$.crt"
106+
kubectl config view --minify --raw -o jsonpath='{.clusters[0].cluster.certificate-authority-data}' | base64 -d > "$CA_FILE"
107+
fi
108+
109+
# 3. Define the desired context name
110+
CONTEXT_NAME="mcp-viewer-context"
111+
KUBECONFIG_FILE="$HOME/.kube/mcp-viewer.kubeconfig"
112+
```
113+
114+
### Step 3.2: Create and Configure the Kubeconfig File
115+
116+
Create the new kubeconfig file by defining the cluster, user (the ServiceAccount), and context:
117+
118+
```bash
119+
# Create a new kubeconfig file with cluster configuration
120+
kubectl config --kubeconfig="$KUBECONFIG_FILE" set-cluster mcp-viewer-cluster \
121+
--server="$API_SERVER" \
122+
--certificate-authority="$CA_FILE" \
123+
--embed-certs=true
124+
125+
# Set the ServiceAccount token as the user credential
126+
kubectl config --kubeconfig="$KUBECONFIG_FILE" set-credentials mcp-viewer \
127+
--token="$TOKEN"
128+
129+
# Define the context (links the cluster and user)
130+
kubectl config --kubeconfig="$KUBECONFIG_FILE" set-context "$CONTEXT_NAME" \
131+
--cluster=mcp-viewer-cluster \
132+
--user=mcp-viewer
133+
134+
# Set the new context as current
135+
kubectl config --kubeconfig="$KUBECONFIG_FILE" use-context "$CONTEXT_NAME"
136+
137+
# Secure the file permissions
138+
chmod 600 "$KUBECONFIG_FILE"
139+
140+
# Clean up temporary CA file if we created one
141+
if [[ "$CA_FILE" == /tmp/k8s-ca-*.crt ]]; then
142+
rm -f "$CA_FILE"
143+
fi
144+
```
145+
146+
### Quick Sanity Check
147+
148+
You can now use this new file to verify access:
149+
150+
```bash
151+
# Run a command using the dedicated kubeconfig file
152+
kubectl --kubeconfig="$KUBECONFIG_FILE" get pods -A
153+
```
154+
155+
This command should successfully list all Pods if you chose **Option A: Cluster-Wide Read-Only**, proving the ServiceAccount and its token are correctly configured.
156+
157+
## 4. Use with Kubernetes MCP Server
158+
159+
Now that you have a dedicated kubeconfig file, you can use it with the Kubernetes MCP Server:
160+
161+
```bash
162+
# Run the MCP server with the dedicated kubeconfig
163+
./kubernetes-mcp-server --kubeconfig="$HOME/.kube/mcp-viewer.kubeconfig"
164+
165+
# Or use npx
166+
npx -y kubernetes-mcp-server@latest --kubeconfig="$HOME/.kube/mcp-viewer.kubeconfig"
167+
168+
# Or use uvx
169+
uvx kubernetes-mcp-server@latest --kubeconfig="$HOME/.kube/mcp-viewer.kubeconfig"
170+
```
171+
172+
Alternatively, you can set the `KUBECONFIG` environment variable:
173+
174+
```bash
175+
export KUBECONFIG="$HOME/.kube/mcp-viewer.kubeconfig"
176+
./kubernetes-mcp-server
177+
```
178+
179+
## Token Expiration and Renewal
180+
181+
The token created in Step 2 has a limited lifetime (2 hours in the example). When it expires, you'll need to:
182+
183+
1. Generate a new token:
184+
```bash
185+
TOKEN="$(kubectl create token mcp-viewer --duration=2h -n mcp)"
186+
```
187+
188+
2. Update the kubeconfig file:
189+
```bash
190+
kubectl config --kubeconfig="$KUBECONFIG_FILE" set-credentials mcp-viewer --token="$TOKEN"
191+
```
192+
193+
For long-running applications, consider:
194+
- Using a longer token duration (up to the cluster's maximum, typically 24h)
195+
- Implementing automatic token renewal in your application
196+
- Using a different authentication method (e.g., client certificates)
197+
198+
## Cleanup
199+
200+
To remove the ServiceAccount and associated RBAC bindings:
201+
202+
```bash
203+
# Delete the ClusterRoleBinding (if using Option A)
204+
kubectl delete clusterrolebinding mcp-viewer-crb
205+
206+
# Delete the RoleBinding (if using Option B)
207+
kubectl delete rolebinding mcp-viewer-rb -n mcp
208+
209+
# Delete the ServiceAccount
210+
kubectl delete serviceaccount mcp-viewer -n mcp
211+
212+
# Delete the namespace (optional - only if you created it specifically for this)
213+
kubectl delete namespace mcp
214+
215+
# Remove the kubeconfig file
216+
rm "$HOME/.kube/mcp-viewer.kubeconfig"
217+
```
218+
219+
## Troubleshooting
220+
221+
### kubectl create token: command not found
222+
223+
This command requires Kubernetes v1.24+. For older versions, you'll need to extract the token from the ServiceAccount's secret manually.
224+
225+
### Permission denied errors
226+
227+
Ensure you're using the correct kubeconfig file and that the ServiceAccount has the necessary RBAC permissions. Verify with:
228+
229+
```bash
230+
kubectl auth can-i list pods --as=system:serviceaccount:mcp:mcp-viewer --all-namespaces
231+
```
232+
233+
## Next Steps
234+
235+
Now that you have a working kubeconfig with read-only access, configure Claude Code CLI:
236+
237+
- **[Using with Claude Code CLI](GETTING_STARTED_CLAUDE_CODE.md)** - Configure the MCP server with Claude Code CLI
238+
239+
You can also:
240+
- Explore the [main README](../README.md) for more MCP server capabilities

‎docs/README.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Kubernetes MCP Server Documentation
2+
3+
Welcome to the Kubernetes MCP Server documentation! This directory contains guides to help you set up and use the Kubernetes MCP Server with your Kubernetes cluster and Claude Code CLI.
4+
5+
## Getting Started Guides
6+
7+
Choose the guide that matches your needs:
8+
9+
| Guide | Description | Best For |
10+
|-------|-------------|----------|
11+
| **[Getting Started with Kubernetes](GETTING_STARTED_KUBERNETES.md)** | Base setup: Create ServiceAccount, token, and kubeconfig | Everyone - **start here first** |
12+
| **[Using with Claude Code CLI](GETTING_STARTED_CLAUDE_CODE.md)** | Configure MCP server with Claude Code CLI | Claude Code CLI users |
13+
14+
## Recommended Workflow
15+
16+
1. **Complete the base setup**: Start with [Getting Started with Kubernetes](GETTING_STARTED_KUBERNETES.md) to create a ServiceAccount and kubeconfig file
17+
2. **Configure Claude Code**: Then follow the [Claude Code CLI guide](GETTING_STARTED_CLAUDE_CODE.md)
18+
19+
## Additional Documentation
20+
21+
- **[Main README](../README.md)** - Project overview and general information

0 commit comments

Comments
 (0)