kubectl-mcp-server 1.8.0 → 1.10.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +218 -8
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -5,10 +5,27 @@ A Model Context Protocol (MCP) server for Kubernetes that enables AI assistants
|
|
|
5
5
|
[](https://opensource.org/licenses/MIT)
|
|
6
6
|
[](https://www.python.org/)
|
|
7
7
|
[](https://kubernetes.io/)
|
|
8
|
-
[](https://
|
|
9
|
-
[](https://modelcontextprotocol.io)
|
|
9
|
+
[](https://pypi.org/project/kubectl-mcp-tool/)
|
|
10
|
+
[](https://www.npmjs.com/package/kubectl-mcp-server)
|
|
11
11
|
[](https://hub.docker.com/r/rohitghumare64/kubectl-mcp-server)
|
|
12
|
+
[](https://github.com/rohitg00/kubectl-mcp-server)
|
|
13
|
+
|
|
14
|
+
## MCP Client Compatibility
|
|
15
|
+
|
|
16
|
+
Works with all MCP-compatible AI assistants:
|
|
17
|
+
|
|
18
|
+
| Client | Status | Client | Status |
|
|
19
|
+
|--------|--------|--------|--------|
|
|
20
|
+
| Claude Desktop | ✅ Native | Claude Code | ✅ Native |
|
|
21
|
+
| Cursor | ✅ Native | Windsurf | ✅ Native |
|
|
22
|
+
| GitHub Copilot | ✅ Native | OpenAI Codex | ✅ Native |
|
|
23
|
+
| Gemini CLI | ✅ Native | Goose | ✅ Native |
|
|
24
|
+
| Roo Code | ✅ Native | Kilo Code | ✅ Native |
|
|
25
|
+
| Amp | ✅ Native | Trae | ✅ Native |
|
|
26
|
+
| OpenCode | ✅ Native | Kiro CLI | ✅ Native |
|
|
27
|
+
| Antigravity | ✅ Native | Clawdbot | ✅ Native |
|
|
28
|
+
| Droid (Factory) | ✅ Native | Any MCP Client | ✅ Compatible |
|
|
12
29
|
|
|
13
30
|
## Live Demos
|
|
14
31
|
|
|
@@ -23,7 +40,7 @@ A Model Context Protocol (MCP) server for Kubernetes that enables AI assistants
|
|
|
23
40
|
|
|
24
41
|
## Features
|
|
25
42
|
|
|
26
|
-
###
|
|
43
|
+
### 121 MCP Tools for Complete Kubernetes Management
|
|
27
44
|
|
|
28
45
|
| Category | Tools |
|
|
29
46
|
|----------|-------|
|
|
@@ -36,7 +53,11 @@ A Model Context Protocol (MCP) server for Kubernetes that enables AI assistants
|
|
|
36
53
|
| **Cluster** | `get_nodes`, `get_namespaces`, `get_cluster_info`, `get_cluster_version`, `health_check`, `get_node_metrics`, `get_pod_metrics` |
|
|
37
54
|
| **RBAC & Security** | `get_rbac_roles`, `get_cluster_roles`, `get_service_accounts`, `audit_rbac_permissions`, `check_secrets_security`, `get_pod_security_info`, `get_admission_webhooks` |
|
|
38
55
|
| **CRDs** | `get_crds`, `get_priority_classes` |
|
|
39
|
-
| **Helm** | `
|
|
56
|
+
| **Helm Releases** | `helm_list`, `helm_status`, `helm_history`, `helm_get_values`, `helm_get_manifest`, `helm_get_notes`, `helm_get_hooks`, `helm_get_all` |
|
|
57
|
+
| **Helm Charts** | `helm_show_chart`, `helm_show_values`, `helm_show_readme`, `helm_show_crds`, `helm_show_all`, `helm_search_repo`, `helm_search_hub` |
|
|
58
|
+
| **Helm Repos** | `helm_repo_list`, `helm_repo_add`, `helm_repo_remove`, `helm_repo_update` |
|
|
59
|
+
| **Helm Operations** | `install_helm_chart`, `upgrade_helm_chart`, `uninstall_helm_chart`, `helm_rollback`, `helm_test`, `helm_template`, `helm_template_apply` |
|
|
60
|
+
| **Helm Development** | `helm_create`, `helm_lint`, `helm_package`, `helm_pull`, `helm_dependency_list`, `helm_dependency_update`, `helm_dependency_build`, `helm_version`, `helm_env` |
|
|
40
61
|
| **Context** | `get_current_context`, `switch_context`, `list_contexts`, `list_kubeconfig_contexts` |
|
|
41
62
|
| **Diagnostics** | `diagnose_pod_crash`, `detect_pending_pods`, `get_evicted_pods`, `compare_namespaces` |
|
|
42
63
|
| **Operations** | `kubectl_apply`, `kubectl_create`, `kubectl_describe`, `kubectl_patch`, `delete_resource`, `kubectl_cp`, `backup_resource`, `label_resource`, `annotate_resource`, `taint_node`, `wait_for_condition` |
|
|
@@ -189,6 +210,66 @@ Add to `~/.config/windsurf/mcp.json`:
|
|
|
189
210
|
}
|
|
190
211
|
```
|
|
191
212
|
|
|
213
|
+
### GitHub Copilot (VS Code)
|
|
214
|
+
|
|
215
|
+
Add to VS Code `settings.json`:
|
|
216
|
+
|
|
217
|
+
```json
|
|
218
|
+
{
|
|
219
|
+
"mcp": {
|
|
220
|
+
"servers": {
|
|
221
|
+
"kubernetes": {
|
|
222
|
+
"command": "npx",
|
|
223
|
+
"args": ["-y", "kubectl-mcp-server"]
|
|
224
|
+
}
|
|
225
|
+
}
|
|
226
|
+
}
|
|
227
|
+
}
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
### Goose
|
|
231
|
+
|
|
232
|
+
Add to `~/.config/goose/config.yaml`:
|
|
233
|
+
|
|
234
|
+
```yaml
|
|
235
|
+
extensions:
|
|
236
|
+
kubernetes:
|
|
237
|
+
command: npx
|
|
238
|
+
args:
|
|
239
|
+
- -y
|
|
240
|
+
- kubectl-mcp-server
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
### Gemini CLI
|
|
244
|
+
|
|
245
|
+
Add to `~/.gemini/settings.json`:
|
|
246
|
+
|
|
247
|
+
```json
|
|
248
|
+
{
|
|
249
|
+
"mcpServers": {
|
|
250
|
+
"kubernetes": {
|
|
251
|
+
"command": "npx",
|
|
252
|
+
"args": ["-y", "kubectl-mcp-server"]
|
|
253
|
+
}
|
|
254
|
+
}
|
|
255
|
+
}
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
### Roo Code / Kilo Code
|
|
259
|
+
|
|
260
|
+
Add to `~/.config/roo-code/mcp.json` or `~/.config/kilo-code/mcp.json`:
|
|
261
|
+
|
|
262
|
+
```json
|
|
263
|
+
{
|
|
264
|
+
"mcpServers": {
|
|
265
|
+
"kubernetes": {
|
|
266
|
+
"command": "npx",
|
|
267
|
+
"args": ["-y", "kubectl-mcp-server"]
|
|
268
|
+
}
|
|
269
|
+
}
|
|
270
|
+
}
|
|
271
|
+
```
|
|
272
|
+
|
|
192
273
|
### Using Python Directly
|
|
193
274
|
|
|
194
275
|
If you prefer Python over npx:
|
|
@@ -234,6 +315,29 @@ python -m kubectl_mcp_tool.mcp_server --transport http --port 8000
|
|
|
234
315
|
| `MCP_DEBUG` | Set to `1` for verbose logging |
|
|
235
316
|
| `MCP_LOG_FILE` | Path to log file |
|
|
236
317
|
|
|
318
|
+
### Authentication (Enterprise)
|
|
319
|
+
|
|
320
|
+
| Variable | Description |
|
|
321
|
+
|----------|-------------|
|
|
322
|
+
| `MCP_AUTH_ENABLED` | Enable OAuth 2.1 authentication (default: `false`) |
|
|
323
|
+
| `MCP_AUTH_ISSUER` | OAuth 2.0 Authorization Server URL |
|
|
324
|
+
| `MCP_AUTH_JWKS_URI` | JWKS endpoint (optional, derived from issuer) |
|
|
325
|
+
| `MCP_AUTH_AUDIENCE` | Expected token audience (default: `kubectl-mcp-server`) |
|
|
326
|
+
| `MCP_AUTH_REQUIRED_SCOPES` | Required scopes (default: `mcp:tools`) |
|
|
327
|
+
|
|
328
|
+
## MCP Authorization (RFC 9728)
|
|
329
|
+
|
|
330
|
+
For enterprise deployments, kubectl-mcp-server supports OAuth 2.1 authentication.
|
|
331
|
+
|
|
332
|
+
```bash
|
|
333
|
+
export MCP_AUTH_ENABLED=true
|
|
334
|
+
export MCP_AUTH_ISSUER=https://your-idp.example.com
|
|
335
|
+
export MCP_AUTH_AUDIENCE=kubectl-mcp-server
|
|
336
|
+
kubectl-mcp-server --transport http --port 8000
|
|
337
|
+
```
|
|
338
|
+
|
|
339
|
+
Supported identity providers: **Okta**, **Auth0**, **Keycloak**, **Microsoft Entra ID**, **Google OAuth**, and any OIDC-compliant provider.
|
|
340
|
+
|
|
237
341
|
## Docker MCP Toolkit
|
|
238
342
|
|
|
239
343
|
Compatible with [Docker MCP Toolkit](https://docs.docker.com/ai/mcp-catalog-and-toolkit/toolkit/):
|
|
@@ -250,6 +354,88 @@ docker mcp server enable kubectl-mcp-server
|
|
|
250
354
|
docker mcp client connect claude
|
|
251
355
|
```
|
|
252
356
|
|
|
357
|
+
## Kubernetes Deployment
|
|
358
|
+
|
|
359
|
+
Deploy kubectl-mcp-server directly in your Kubernetes cluster for centralized access.
|
|
360
|
+
|
|
361
|
+
### kMCP Deployment (Recommended)
|
|
362
|
+
|
|
363
|
+
[kMCP](https://github.com/kagent-dev/kmcp) is a development platform and control plane for MCP servers. See [kMCP quickstart](https://kagent.dev/docs/kmcp/quickstart).
|
|
364
|
+
|
|
365
|
+
```bash
|
|
366
|
+
# Install kmcp CLI
|
|
367
|
+
curl -fsSL https://raw.githubusercontent.com/kagent-dev/kmcp/refs/heads/main/scripts/get-kmcp.sh | bash
|
|
368
|
+
|
|
369
|
+
# Install kmcp controller in your cluster
|
|
370
|
+
helm install kmcp-crds oci://ghcr.io/kagent-dev/kmcp/helm/kmcp-crds \
|
|
371
|
+
--namespace kmcp-system --create-namespace
|
|
372
|
+
kmcp install
|
|
373
|
+
|
|
374
|
+
# Deploy kubectl-mcp-server using npx (easiest)
|
|
375
|
+
kmcp deploy package --deployment-name kubectl-mcp-server \
|
|
376
|
+
--manager npx --args kubectl-mcp-server
|
|
377
|
+
|
|
378
|
+
# Or deploy using our Docker image with the MCPServer manifest
|
|
379
|
+
kmcp deploy --file deploy/kmcp/kmcp.yaml --image rohitghumare64/kubectl-mcp-server:latest
|
|
380
|
+
```
|
|
381
|
+
|
|
382
|
+
### Standard Kubernetes Deployment
|
|
383
|
+
|
|
384
|
+
Deploy using kubectl/kustomize without kMCP:
|
|
385
|
+
|
|
386
|
+
```bash
|
|
387
|
+
# Using kustomize (recommended)
|
|
388
|
+
kubectl apply -k deploy/kubernetes/
|
|
389
|
+
|
|
390
|
+
# Or apply individual manifests
|
|
391
|
+
kubectl apply -f deploy/kubernetes/namespace.yaml
|
|
392
|
+
kubectl apply -f deploy/kubernetes/rbac.yaml
|
|
393
|
+
kubectl apply -f deploy/kubernetes/deployment.yaml
|
|
394
|
+
kubectl apply -f deploy/kubernetes/service.yaml
|
|
395
|
+
|
|
396
|
+
# Access via port-forward
|
|
397
|
+
kubectl port-forward -n kubectl-mcp svc/kubectl-mcp-server 8000:8000
|
|
398
|
+
```
|
|
399
|
+
|
|
400
|
+
### MCPServer Custom Resource
|
|
401
|
+
|
|
402
|
+
For kMCP deployments, apply this MCPServer resource:
|
|
403
|
+
|
|
404
|
+
```yaml
|
|
405
|
+
apiVersion: kagent.dev/v1alpha1
|
|
406
|
+
kind: MCPServer
|
|
407
|
+
metadata:
|
|
408
|
+
name: kubectl-mcp-server
|
|
409
|
+
spec:
|
|
410
|
+
deployment:
|
|
411
|
+
image: "rohitghumare64/kubectl-mcp-server:latest"
|
|
412
|
+
port: 8000
|
|
413
|
+
transportType: http
|
|
414
|
+
httpTransport:
|
|
415
|
+
targetPort: 8000
|
|
416
|
+
path: /mcp
|
|
417
|
+
```
|
|
418
|
+
|
|
419
|
+
See [deploy/](deploy/) for full manifests and configuration options.
|
|
420
|
+
|
|
421
|
+
### kagent Integration (AI Agents)
|
|
422
|
+
|
|
423
|
+
[kagent](https://github.com/kagent-dev/kagent) is a Kubernetes-native AI agent framework (CNCF project). Register kubectl-mcp-server as a ToolServer to give your agents 121 K8s management tools.
|
|
424
|
+
|
|
425
|
+
```bash
|
|
426
|
+
# Install kagent
|
|
427
|
+
brew install kagent
|
|
428
|
+
kagent install --profile demo
|
|
429
|
+
|
|
430
|
+
# Register kubectl-mcp-server as a ToolServer
|
|
431
|
+
kubectl apply -f deploy/kagent/toolserver-stdio.yaml
|
|
432
|
+
|
|
433
|
+
# Open kagent dashboard and chat with your K8s agent
|
|
434
|
+
kagent dashboard
|
|
435
|
+
```
|
|
436
|
+
|
|
437
|
+
See [kagent quickstart](https://kagent.dev/docs/kagent/getting-started/quickstart) for full documentation.
|
|
438
|
+
|
|
253
439
|
## Architecture
|
|
254
440
|
|
|
255
441
|
```
|
|
@@ -261,6 +447,28 @@ docker mcp client connect claude
|
|
|
261
447
|
|
|
262
448
|
The MCP server implements the [Model Context Protocol](https://github.com/modelcontextprotocol/spec), translating natural language requests into kubectl operations.
|
|
263
449
|
|
|
450
|
+
### Modular Structure
|
|
451
|
+
|
|
452
|
+
```
|
|
453
|
+
kubectl_mcp_tool/
|
|
454
|
+
├── mcp_server.py # Main server (FastMCP, transports)
|
|
455
|
+
├── tools/ # 121 MCP tools organized by category
|
|
456
|
+
│ ├── pods.py # Pod management & diagnostics
|
|
457
|
+
│ ├── deployments.py # Deployments, StatefulSets, DaemonSets
|
|
458
|
+
│ ├── core.py # Namespaces, ConfigMaps, Secrets
|
|
459
|
+
│ ├── cluster.py # Context/cluster management
|
|
460
|
+
│ ├── networking.py # Services, Ingress, NetworkPolicies
|
|
461
|
+
│ ├── storage.py # PVCs, StorageClasses, PVs
|
|
462
|
+
│ ├── security.py # RBAC, ServiceAccounts, PodSecurity
|
|
463
|
+
│ ├── helm.py # Complete Helm v3 operations
|
|
464
|
+
│ ├── operations.py # kubectl apply/patch/describe/etc
|
|
465
|
+
│ ├── diagnostics.py # Metrics, namespace comparison
|
|
466
|
+
│ └── cost.py # Resource optimization & cost analysis
|
|
467
|
+
├── resources/ # 8 MCP Resources for data exposure
|
|
468
|
+
├── prompts/ # 8 MCP Prompts for workflows
|
|
469
|
+
└── cli/ # CLI interface
|
|
470
|
+
```
|
|
471
|
+
|
|
264
472
|
## Multi-Cluster Support
|
|
265
473
|
|
|
266
474
|
```bash
|
|
@@ -313,12 +521,14 @@ pytest tests/ -v -m unit
|
|
|
313
521
|
tests/
|
|
314
522
|
├── __init__.py # Test package
|
|
315
523
|
├── conftest.py # Shared fixtures and mocks
|
|
316
|
-
├── test_tools.py # Unit tests for
|
|
317
|
-
├── test_resources.py # Tests for MCP Resources
|
|
318
|
-
├── test_prompts.py # Tests for MCP Prompts
|
|
524
|
+
├── test_tools.py # Unit tests for 121 MCP tools
|
|
525
|
+
├── test_resources.py # Tests for 8 MCP Resources
|
|
526
|
+
├── test_prompts.py # Tests for 8 MCP Prompts
|
|
319
527
|
└── test_server.py # Server initialization tests
|
|
320
528
|
```
|
|
321
529
|
|
|
530
|
+
**138 tests covering**: tool registration, resource exposure, prompt generation, server initialization, non-destructive mode, secret masking, error handling, and transport methods.
|
|
531
|
+
|
|
322
532
|
### Code Quality
|
|
323
533
|
|
|
324
534
|
```bash
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "kubectl-mcp-server",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.10.0",
|
|
4
4
|
"description": "A Model Context Protocol (MCP) server for Kubernetes that enables AI assistants like Claude, Cursor, and others to interact with Kubernetes clusters through natural language",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"kubernetes",
|