io.github.apatilgtn/k8scortex-mcp
Kubernetes MCP server: 75 tools for GKE, AKS, EKS, RBAC, audit logging, GitOps, multi-cluster.
Ask AI about io.github.apatilgtn/k8scortex-mcp
Powered by Claude Β· Grounded in docs
I know everything about io.github.apatilgtn/k8scortex-mcp. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
K8sCortex β Kubernetes MCP Server
A production-grade Model Context Protocol (MCP) server that gives developers, AI agents, and automation pipelines a single, secure, natural-language interface to Kubernetes β across any cloud, any cluster, any team.
Features
- Curated multi-domain toolset across workload, deployment, configuration, observability, jobs, networking, GitOps, cluster admin, and generic read paths
- Multi-cluster routing β target any registered cluster with a single
clusterparameter - Entra ID OIDC authentication with per-tool RBAC (5-tier role hierarchy)
- Structured audit logging β every tool call recorded with caller identity, arguments, and outcome
- Dual transport β SSE/HTTP for programmatic clients + stdio for Claude Desktop
- Azure Key Vault integration for dynamic credential management with 5-minute TTL cache
- Dry-run safety β destructive tools default to simulation mode
- Generic read coverage β list/get support for resources outside curated write paths to avoid troubleshooting dead-ends
Install via npx (Fastest)
npx k8scortex-mcp
Or install globally:
npm install -g k8scortex-mcp
Quick Start
Prerequisites
- Node.js β₯ 18
- A Kubernetes cluster (minikube, Rancher Desktop, or AKS)
kubectlconfigured with a valid context
Install & Run
# Clone
git clone https://github.com/apatilgtn/k8scortex-mcp.git
cd k8scortex-mcp
# Install
npm install
# Build
npm run build
# Run (local dev mode β auth bypassed)
DISABLE_AUTH=true PORT=3001 npm run dev
Connect with MCP Inspector
npx @modelcontextprotocol/inspector sse http://localhost:3001/mcp
Connect with Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"k8scortex": {
"command": "node",
"args": ["<path-to>/k8scortex-mcp/dist/stdio.js"],
"env": {
"DISABLE_AUTH": "true",
"KUBECONFIG": "~/.kube/config"
}
}
}
}
Restart Claude Desktop. Ask: "List all pods in the default namespace".
Tools
K8sCortex intentionally keeps writes curated and governed, while allowing flexible read access for diagnostics.
| Domain | Tool | Description |
|---|---|---|
| Workload | list_pods | List pods with status and IP |
| Workload | get_pod_logs | Fetch container logs |
| Workload | describe_deployment | Full deployment spec |
| Workload | list_statefulsets | List StatefulSets with rollout status |
| Workload | describe_statefulset | Detailed StatefulSet spec/status |
| Workload | list_daemonsets | List DaemonSets with scheduling status |
| Workload | describe_daemonset | Detailed DaemonSet spec/status |
| Workload | list_nodes | Cluster nodes with Ready status |
| Deploy | scale_deployment | Scale replicas (dry-run default) |
| Deploy | restart_pod | Delete pod to trigger restart |
| Config | get_configmap | Read ConfigMap data |
| Config | describe_namespace_quota | Resource quota usage |
| Config | list_events | Recent namespace events |
| Config | list_persistent_volume_claims | PVC status, bound volume, storage class, capacity |
| Config | get_effective_permissions | ServiceAccount SubjectAccessReview matrix |
| Generic Read | list_k8s_resources | Generic list for arbitrary resource kinds |
| Generic Read | get_k8s_resource | Generic get for arbitrary resource kinds |
| Observe | get_hpa_status | HPA metrics and scaling |
| Observe | list_warning_events | Warning events for triage |
| Observe | get_node_pressure | Node memory/disk/PID pressure |
| Multi | list_clusters | All registered clusters |
| Multi | get_cluster_info | Node count, versions, architecture |
For the evolving full catalog, see docs/developer-guide.md.
Managed Risk
The largest functional risk in Kubernetes MCP is dead-end visibility on non-curated resources (for example StatefulSets, DaemonSets, PVCs, or CRDs). KubeNexus addresses this by combining:
- Governed writes: high-impact operations remain explicit, role-gated, and often dry-run by default.
- Flexible reads: generic read tools cover arbitrary resource kinds for diagnostics.
This keeps the governance posture strong while preserving practical troubleshooting coverage.
Scope Boundaries (v1)
K8sCortex is designed as a governed platform interface, not an unrestricted Kubernetes super-client.
- Generic write for any resource: intentionally out of scope in v1. Writes are curated and role-gated by design.
- Pod exec interactive sessions: intentionally out of scope in v1. This requires stronger session controls and command-level auditing that are planned for a later version.
Architecture
Claude / Prism Agent / CI-CD
β
βΌ
ββββββββββββββββββββββββββββββββ
β K8sCortex MCP Server β
β OIDC β RBAC β Tool β Audit β
β β β
β Cluster Store (Key Vault) β
ββββββββββββ¬ββββββββββββββββββββ
β
ββββββββΌβββββββ
βΌ βΌ βΌ
AKS EKS GKE
Security
- Authentication: Entra ID OIDC tokens validated on every request
- Authorization: Role-based tool access (
developerβplatform-engineer) - Audit: JSON-structured log per invocation with user, tool, args, status
- Network: ClusterIP only β no public endpoint
- Credentials: Key Vault with 5-minute TTL cache, no kubeconfigs on disk
Project Structure
src/
βββ index.ts # Express SSE server
βββ stdio.ts # Stdio entry point (Claude Desktop)
βββ auth.ts # OIDC middleware
βββ roles.ts # RBAC role hierarchy
βββ audit.ts # Audit logger
βββ context.ts # AsyncLocalStorage user context
βββ cluster-store.ts # Dynamic K8s client factory
βββ kubernetes.ts # Client re-export
βββ tools/
βββ workload.ts # list_pods, get_pod_logs, describe_deployment, list_nodes
βββ deployment.ts # scale_deployment, restart_pod
βββ configuration.ts # get_configmap, describe_namespace_quota, list_events
βββ observability.ts # get_hpa_status, list_warning_events, get_node_pressure
βββ multicluster.ts # list_clusters, get_cluster_info
kubernetes/ # Production manifests
βββ namespace.yaml
βββ deployment.yaml
βββ service.yaml
βββ rbac.yaml
βββ network-policy.yaml
βββ hpa.yaml
βββ secret-provider-class.yaml
βββ alerts.yaml # Prometheus alerting rules
docs/
βββ developer-guide.md # End-user documentation
βββ operator-runbook.md # Platform team operations
βββ slos.md # Service level objectives
βββ adrs/ # Architecture decision records
βββ ADR-001-tool-taxonomy.md
βββ ADR-002-idp-integration.md
βββ ADR-003-role-model.md
βββ ADR-004-credential-management.md
Documentation
- Developer Guide β How to connect, available tools, example queries
- Operator Runbook β Deploy, upgrade, rotate credentials, incident response
- SLOs β Availability, latency, and alerting targets
Document Files
- Word documents are consolidated in docs/docx.
- Current files:
K8sCortex_Cloud_Testing_Publishing_Plan.docxK8sCortex_Project_Plan.docxK8sCortex_Project_Plan_v3.docxK8sCortex_Project_Plan_v4.docx
License
Internal β Platform Engineering
