{"id":48027178,"url":"https://github.com/tamcore/kubectl-mcp","last_synced_at":"2026-04-04T13:52:18.839Z","repository":{"id":344663600,"uuid":"1182393433","full_name":"tamcore/kubectl-mcp","owner":"tamcore","description":null,"archived":false,"fork":false,"pushed_at":"2026-03-25T09:25:34.000Z","size":548,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-03-25T17:54:13.808Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tamcore.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-15T13:13:03.000Z","updated_at":"2026-03-25T09:25:37.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tamcore/kubectl-mcp","commit_stats":null,"previous_names":["tamcore/kubectl-mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/tamcore/kubectl-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tamcore%2Fkubectl-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tamcore%2Fkubectl-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tamcore%2Fkubectl-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tamcore%2Fkubectl-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tamcore","download_url":"https://codeload.github.com/tamcore/kubectl-mcp/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tamcore%2Fkubectl-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31402276,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T10:20:44.708Z","status":"ssl_error","status_checked_at":"2026-04-04T10:20:06.846Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-04T13:52:18.305Z","updated_at":"2026-04-04T13:52:18.834Z","avatar_url":"https://github.com/tamcore.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# kubectl-mcp\n\n\u003e Built with ❤️ by AI, for AI.\n\nA minimalistic Kubernetes MCP (Model Context Protocol) server that\nlets LLMs query and manage your clusters safely.\n\n## Features\n\n- **Read-only by default** — no accidental mutations\n- **Secrets redacted by default** — `.data` and `.stringData` replaced with `\u003credacted\u003e`\n- **Multi-kubeconfig** — honours `KUBECONFIG` with colon-separated paths\n- **Context filtering** — allow/deny contexts via glob (`prod-*`) or regex (`/^staging-.+$/`)\n- **Three transports** — stdio (default), SSE, and streamable-HTTP\n- **Write operations** — opt-in via `--allow-write` for apply, patch, scale, restart, cordon, uncordon, exec, rollout undo, run, port-forward\n- **Destructive operations** — opt-in via `--allow-destructive` for delete and drain\n- **Raw API access** — opt-in via `--allow-raw` for direct Kubernetes API requests (bypasses secret redaction; non-GET additionally requires `--allow-write`)\n- **Fuzzy kind matching** — resolves short names (`deploy`, `svc`) and suggests corrections for typos\n- **Rate limiting** — configurable per-minute limits for read and write operations\n- **MCP tool annotations** — every tool declares `readOnlyHint`, `destructiveHint`, `idempotentHint`, and `openWorldHint` so MCP clients can make informed decisions\n- **Elicitation confirmation** — destructive operations (delete, drain) prompt for user confirmation via MCP elicitation\n- **Structured content** — get, list, and describe responses include machine-readable structured content alongside text\n- **35 MCP tools** — 19 read-only + 12 write + 3 destructive + 1 raw\n- **MCP resources** — read any Kubernetes resource via `k8s://` URI scheme (2 resource templates)\n\n## Installation\n\n```bash\ngo install github.com/tamcore/kubectl-mcp/cmd/kubectl-mcp@latest\n```\n\n## Usage\n\n```bash\n# Start with stdio transport (default)\nkubectl-mcp serve\n\n# Start with SSE transport\nkubectl-mcp serve --transport sse --sse-address :9090\n\n# Start with streamable-HTTP transport\nkubectl-mcp serve --transport streamable-http --http-address :9090\n\n# Use a specific kubeconfig and context\nkubectl-mcp serve --kubeconfig ~/.kube/config --context my-cluster\n\n# Allow secrets and restrict to specific contexts\nkubectl-mcp serve --allow-secrets --allowed-contexts \"dev-*,staging-*\"\n\n# Deny production contexts\nkubectl-mcp serve --denied-contexts \"/^prod-/\"\n\n# Enable write operations\nkubectl-mcp serve --allow-write\n\n# Enable all operations including delete and drain\nkubectl-mcp serve --allow-write --allow-destructive\n\n# Enable raw API access (bypasses secret redaction)\nkubectl-mcp serve --allow-write --allow-raw\n```\n\n## Configuration\n\nAll flags can also be set via environment variables with a `KUBECTL_MCP_` prefix.\n`KUBECONFIG` is honoured directly.\n\n| Flag | Env Var | Default | Description |\n|------|---------|---------|-------------|\n| `--transport` | `KUBECTL_MCP_TRANSPORT` | `stdio` | Transport: `stdio`, `sse`, or `streamable-http` |\n| `--sse-address` | `KUBECTL_MCP_SSE_ADDRESS` | `:8080` | SSE listen address |\n| `--http-address` | `KUBECTL_MCP_HTTP_ADDRESS` | `:8080` | Streamable-HTTP listen address |\n| `--kubeconfig` | `KUBECONFIG` | `~/.kube/config` | Colon-separated kubeconfig paths |\n| `--context` | `KUBECTL_MCP_CONTEXT` | *(current-context)* | Default kube-context override |\n| `--allowed-contexts` | `KUBECTL_MCP_ALLOWED_CONTEXTS` | `*` | Comma-separated glob/regex allow patterns |\n| `--denied-contexts` | `KUBECTL_MCP_DENIED_CONTEXTS` | *(none)* | Comma-separated glob/regex deny patterns |\n| `--allow-write` | `KUBECTL_MCP_ALLOW_WRITE` | `false` | Enable write operations (apply, patch, scale, restart, cordon, uncordon, exec, rollout undo, rollout pause/resume, run, port-forward) |\n| `--allow-destructive` | `KUBECTL_MCP_ALLOW_DESTRUCTIVE` | `false` | Enable destructive operations (delete, drain, cleanup-pods); implies `--allow-write` |\n| `--allow-raw` | `KUBECTL_MCP_ALLOW_RAW` | `false` | Enable raw Kubernetes API requests (`api_raw` tool); non-GET methods additionally require `--allow-write` |\n| `--allow-secrets` | `KUBECTL_MCP_ALLOW_SECRETS` | `false` | Allow reading Secret data |\n| `--rate-limit-read` | `KUBECTL_MCP_RATE_LIMIT_READ` | `120` | Max read tool calls per minute (0 = unlimited) |\n| `--rate-limit-write` | `KUBECTL_MCP_RATE_LIMIT_WRITE` | `30` | Max write tool calls per minute (0 = unlimited) |\n| `--log-level` | `KUBECTL_MCP_LOG_LEVEL` | `info` | Logging verbosity: `off`, `info`, or `debug` |\n| `--log-dir` | `KUBECTL_MCP_LOG_DIR` | `~/.kubectl-mcp/` | Directory for per-context log files |\n| `--log-file` | `KUBECTL_MCP_LOG_FILE` | *(auto)* | Deprecated: use `--log-dir` instead |\n\n### Logging\n\nWhen logging is enabled (`--log-level info` or `debug`), the server writes **per-kubecontext log files** under a PID-scoped subdirectory:\n\n```\n~/.kubectl-mcp/\u003cpid\u003e/\n├── server.log          # Server lifecycle (startup, shutdown, errors)\n├── kind-e2e.log        # Tool calls targeting the kind-e2e context\n├── prod-cluster.log    # Tool calls targeting prod-cluster\n└── staging.log         # Tool calls targeting staging\n```\n\nEach tool call is routed to the log file matching the target kubecontext. The `context` parameter from the tool request determines the file; if omitted, the default context is used.\n\n### Context Filtering\n\nContexts are allowed if they match at least one `--allowed-contexts` pattern\n**and** do not match any `--denied-contexts` pattern. Deny takes precedence.\n\n- **Glob patterns:** `prod-*`, `dev-??`, `*-staging`\n- **Regex patterns:** Wrap in forward slashes: `/^prod-.+$/`\n\n## MCP Tools\n\nAll tools accept an optional `context` parameter to target a specific\nkube-context. If omitted, the configured default context is used.\n\n### Read-only tools (always available)\n\n| Tool | Description |\n|------|-------------|\n| `list_contexts` | List available (allowed) kube-contexts |\n| `list_namespaces` | List namespaces |\n| `list_api_resources` | List API resources (kind, apiVersion, namespaced, verbs) |\n| `get_resource` | Get a single resource as JSON |\n| `list_resources` | List resources with label/field selectors, pagination, client-side filters, sortBy, and allNamespaces support |\n| `describe_resource` | Rich describe output with conditions, spec, and events |\n| `get_logs` | Get pod/container logs (supports label selectors, timestamps, sinceTime, follow/streaming, multi-pod prefix, resource references like deployment/nginx) |\n| `get_events` | Get cluster events (supports allNamespaces) |\n| `top_pods` | Get CPU/memory usage for pods (requires metrics-server) |\n| `top_nodes` | Get CPU/memory usage for nodes with allocatable percentages |\n| `rollout_status` | Get rollout status of a Deployment, StatefulSet, or DaemonSet |\n| `rollout_history` | Show rollout revision history of a Deployment |\n| `explain_resource` | Explain a resource kind (metadata, verbs, scope) via discovery API |\n| `node_logs` | Get logs from a node via the kubelet proxy |\n| `node_stats` | Get node-level resource usage (CPU, memory, filesystem) from the kubelet stats/summary API |\n| `stop_port_forward` | Stop an active port-forward session or list all active sessions |\n| `list_rbac_bindings` | List ClusterRoleBindings or RoleBindings with optional subject/kind filter |\n| `list_rbac_roles` | List ClusterRoles or Roles; get detailed rules for a named role |\n| `list_service_accounts` | List ServiceAccounts or get details (exposes secret names, never token data) |\n\n### Write tools (require `--allow-write`)\n\n| Tool | Description |\n|------|-------------|\n| `apply_resource` | Apply a JSON/YAML manifest with optional dry-run and field validation level |\n| `patch_resource` | Patch a resource (json, merge, or strategic) with optional dry-run |\n| `scale_resource` | Scale a Deployment, StatefulSet, or ReplicaSet |\n| `restart_rollout` | Restart a Deployment, StatefulSet, or DaemonSet rollout |\n| `cordon_node` | Mark a node as unschedulable |\n| `uncordon_node` | Mark a node as schedulable |\n| `exec_pod` | Execute a command in a pod container (with timeout) |\n| `rollout_undo` | Undo a Deployment rollout to a previous revision |\n| `rollout_pause` | Pause a Deployment rollout |\n| `rollout_resume` | Resume a paused Deployment rollout |\n| `run_pod` | Create and run a pod with a given image (like `kubectl run`) |\n| `port_forward` | Forward a local port to a pod, service, deployment, or statefulset port (with auto-timeout) |\n\n### Destructive tools (require `--allow-destructive`)\n\n| Tool | Description |\n|------|-------------|\n| `delete_resource` | Delete a resource with optional dry-run, grace period, and force deletion (with elicitation confirmation) |\n| `drain_node` | Cordon a node and evict all eligible pods with optional force and timeout (with elicitation confirmation) |\n| `cleanup_pods` | Delete pods in error states (Evicted, Failed, Succeeded) from a namespace |\n\n### Raw API tools (require `--allow-raw`)\n\n| Tool | Description |\n|------|-------------|\n| `api_raw` | Send a raw HTTP request to the Kubernetes API server (equivalent to `kubectl get --raw`). WARNING: bypasses secret redaction. Non-GET methods also require `--allow-write`. |\n\n## MCP Resources\n\nResources expose Kubernetes objects via `k8s://` URIs, allowing MCP clients\nto read cluster state directly.\n\n### URI Scheme\n\nTwo URI patterns are supported:\n\n| Pattern | Scope |\n|---------|-------|\n| `k8s://{context}/namespaces/{namespace}/{group}/{version}/{resource}/{name}` | Namespaced resources |\n| `k8s://{context}/{group}/{version}/{resource}/{name}` | Cluster-scoped resources |\n\nUse `core` as the group for core API resources (pods, services, configmaps, nodes, etc.).\n\n### Examples\n\n```\nk8s://my-cluster/namespaces/default/core/v1/pods/nginx\nk8s://my-cluster/namespaces/kube-system/apps/v1/deployments/coredns\nk8s://my-cluster/core/v1/nodes/worker-1\nk8s://my-cluster/core/v1/namespaces/kube-system\nk8s://my-cluster/namespaces/default/core/v1/secrets/my-secret\n```\n\nResources respect the `--allow-secrets` flag: Secret data is redacted by default.\nNoisy metadata (managedFields, last-applied-configuration) is automatically stripped.\n\n## MCP Client Configuration\n\n### Claude Code (stdio)\n\n```bash\nclaude mcp add --transport stdio --scope user kubectl -- kubectl-mcp serve\n```\n\nWith options:\n\n```bash\nclaude mcp add --transport stdio --scope user kubectl -- \\\n  kubectl-mcp serve --allow-write --allow-secrets --denied-contexts \"/^prod-/\"\n```\n\nTo run directly from source (e.g. during development):\n\n```bash\nclaude mcp add --transport stdio --scope user kubectl -- \\\n  go run -C /path/to/kubectl-mcp ./cmd/kubectl-mcp serve \\\n  --allow-write --allow-destructive --allow-secrets\n```\n\n\u003e **Note:** Use absolute paths — `~` is not expanded. Use `--scope local` (default) for project-only config.\n\n### Claude Code (SSE)\n\nStart the server, then register it:\n\n```bash\nkubectl-mcp serve --transport sse \u0026\nclaude mcp add --transport sse --scope user kubectl http://localhost:8080/sse\n```\n\n### Claude Code (streamable-HTTP)\n\nStart the server, then register it:\n\n```bash\nkubectl-mcp serve --transport streamable-http \u0026\nclaude mcp add --transport http --scope user kubectl http://localhost:8080/mcp\n```\n\n### GitHub Copilot CLI (stdio)\n\nAdd to `~/.copilot/mcp-config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"kubectl\": {\n      \"type\": \"stdio\",\n      \"command\": \"kubectl-mcp\",\n      \"args\": [\"serve\"],\n      \"tools\": [\"*\"]\n    }\n  }\n}\n```\n\nTo run directly from source (e.g. during development):\n\n```json\n{\n  \"mcpServers\": {\n    \"kubectl\": {\n      \"type\": \"stdio\",\n      \"command\": \"go\",\n      \"args\": [\n        \"run\",\n        \"-C\", \"/path/to/kubectl-mcp\",\n        \"./cmd/kubectl-mcp\",\n        \"serve\",\n        \"--allow-write\",\n        \"--allow-destructive\",\n        \"--allow-secrets\"\n      ],\n      \"tools\": [\"*\"]\n    }\n  }\n}\n```\n\n\u003e **Note:** Use absolute paths — `~` is not expanded in JSON config.\n\n### GitHub Copilot CLI (SSE)\n\nStart the server, then add to `~/.copilot/mcp-config.json`:\n\n```bash\nkubectl-mcp serve --transport sse \u0026\n```\n\n```json\n{\n  \"mcpServers\": {\n    \"kubectl\": {\n      \"type\": \"sse\",\n      \"url\": \"http://localhost:8080/sse\",\n      \"headers\": {},\n      \"tools\": [\"*\"]\n    }\n  }\n}\n```\n\n### GitHub Copilot CLI (streamable-HTTP)\n\nStart the server, then add to `~/.copilot/mcp-config.json`:\n\n```bash\nkubectl-mcp serve --transport streamable-http \u0026\n```\n\n```json\n{\n  \"mcpServers\": {\n    \"kubectl\": {\n      \"type\": \"streamable-http\",\n      \"url\": \"http://localhost:8080/mcp\",\n      \"headers\": {},\n      \"tools\": [\"*\"]\n    }\n  }\n}\n```\n\n## Companion Skill (Claude Code)\n\nkubectl-mcp ships with a companion skill file that teaches Claude Code\neffective Kubernetes workflows, safety patterns, and auto-issue reporting.\n\nInstall it:\n\n```bash\ncp skills/kubectl-mcp.md ~/.claude/skills/\n```\n\nThe skill provides:\n- **Diagnosis workflows** — step-by-step patterns for debugging pods, deployments, and nodes\n- **Safety patterns** — dry-run-first, multi-cluster awareness, common mistakes to avoid\n- **Auto-issue reporting** — when Claude encounters a server bug, it will offer to file an\n  anonymized GitHub issue via `gh` CLI (always asks for your confirmation first)\n\n\u003e The server also embeds concise instructions in the MCP `initialize` response, so all\n\u003e MCP clients get baseline guidance automatically — even without the skill file.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftamcore%2Fkubectl-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftamcore%2Fkubectl-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftamcore%2Fkubectl-mcp/lists"}