Kubernetes

The mcp-kubernetes is a Model Context Protocol (MCP) server that enables AI assistants to interact with Kubernetes clusters. It serves as a bridge between AI tools (like Claude, Cursor, and GitHub Copilot) and Kubernetes, translating natural language requests into Kubernetes operations and returning the results in a format the AI tools can understand.

- Query Kubernetes resources
- Execute kubectl commands
- Manage Kubernetes clusters through natural language interactions
- Diagnose and interpret the states of Kubernetes resources

Container images are no longer produced or supported. Install a released binary locally and configure your MCP client to run it as a stdio subprocess.

Installkubectlif it's not installed yet and add it to your PATH, e.g.

# For Linux curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl" # For MacOS curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/darwin/arm64/kubectl"

Installhelmif it's not installed yet and add it to your PATH, e.g.

curl -sSL https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

Config your MCP servers inClaude Desktop,Cursor,ChatGPT Copilot,Github Copilotand other supported AI clients, e.g.

{ "mcpServers": { "kubernetes": { "command": "<path of binary 'mcp-kubernetes'>", "args": ["--transport", "stdio"], "env": { "KUBECONFIG": "<your-kubeconfig-path>" } } } }

- KUBECONFIG: Path to your kubeconfig file, e.g./home/<username>/.kube/config.
- USE_LEGACY_TOOLS: Set totrueto use multiple specialized kubectl tools instead of the unifiedcall_kubectltool (default:false).

Usage of ./mcp-kubernetes: --access-level string Access level (readonly, readwrite, or admin) (default "readonly") --additional-tools string Comma-separated list of additional tools to support (kubectl is always enabled). Available: helm,cilium,hubble --allow-namespaces string Comma-separated list of namespaces to allow (empty means all allowed) --otlp-endpoint string OTLP endpoint for OpenTelemetry traces (e.g. localhost:4317, default "") --timeout int Timeout for command execution in seconds, default is 60s (default 60) --transport string Transport mechanism to use (stdio only) (default "stdio")

By default, mcp-kubernetes uses a single unifiedcall_kubectltool that consolidates all kubectl operations into one tool interface. This significantly reduces context consumption while maintaining full functionality.

To use the legacy mode with multiple specialized tools (6-7 separate tools), set the environment variable:

{ "mcpServers": { "kubernetes": { "command": "mcp-kubernetes", "env": { "USE_LEGACY_TOOLS": "true" } } } }

The--access-levelflag controls what operations are allowed:

- readonly(default): Only read operations are allowed (get, describe, logs, etc.)
- readwrite: Read and write operations are allowed (create, delete, apply, etc.)
- admin: All operations are allowed, including admin operations (cordon, drain, taint, etc.)

Tools and operations are filtered at registration time based on the access level, so AI assistants only see operations they can actually use.

// Read-only access (default) { "mcpServers": { "kubernetes": { "command": "mcp-kubernetes" } } } // Read-write access { "mcpServers": { "kubernetes": { "command": "mcp-kubernetes", "args": ["--access-level", "readwrite"] } } } // Admin access { "mcpServers": { "kubernetes": { "command": "mcp-kubernetes", "args": ["--access-level", "admin"] } } }

Ask any questions about Kubernetes cluster in your AI client. The MCP tools make it easier for AI assistants to understand and use kubectl operations.

What is the status of my Kubernetes cluster? What is wrong with my nginx pod? Show me all deployments in the production namespace Scale my web deployment to 5 replicas Check if I have permission to create pods What is my current kubectl context? List all available kubectl contexts Switch to the production context

By default, mcp-kubernetes uses a single unifiedcall_kubectltool that handles all kubectl operations. This approach significantly reduces context consumption compared to the legacy multi-tool approach.

- Available in: All access levels (operations filtered by access level)
- Parameters:

- command: The full kubectl command to execute including 'kubectl' prefix (e.g., "kubectl get pods -n default", "kubectl apply -f deployment.yaml")

# Get pods command: "kubectl get pods -n default" # Apply configuration command: "kubectl apply -f deployment.yaml" # Scale deployment command: "kubectl scale deployment nginx --replicas=3"

WhenUSE_LEGACY_TOOLS=true, the mcp-kubernetes server provides multiple specialized kubectl tools that group related operations together. Tools are automatically filtered based on your access level.

Available in: readonly, readwrite, admin

Handles CRUD operations on Kubernetes resources and node management. In readonly mode, only supportsgetanddescribeoperations. Node operations (cordon, uncordon, drain, taint) are available in admin mode only.

- operation: The operation to perform (get, describe, create, delete, apply, patch, replace, cordon, uncordon, drain, taint)
- resource: The resource type (e.g., pods, deployments, services, nodes) or empty for file-based operations
- args: Additional arguments like resource names, namespaces, and flags

# Get all pods operation: "get" resource: "pods" args: "--all-namespaces" # Apply a configuration operation: "apply" resource: "" args: "-f deployment.yaml" # Drain a node (admin only) operation: "drain" resource: "node" args: "worker-1 --ignore-daemonsets" # Add a taint (admin only) operation: "taint" resource: "nodes" args: "worker-1 key=value:NoSchedule"

Manages deployment lifecycle operations including scaling and rollouts.

- operation: The operation to perform (run, expose, scale, autoscale, rollout)
- resource: For rollout operations, the subcommand (status, history, undo, restart, pause, resume)
- args: Additional arguments

# Scale a deployment operation: "scale" resource: "deployment" args: "nginx --replicas=3" # Check rollout status operation: "rollout" resource: "status" args: "deployment/nginx"

Updates labels, annotations, and other metadata on resources.

- operation: The operation to perform (label, annotate, set)
- resource: The resource type
- args: Resource name and metadata changes

# Add a label operation: "label" resource: "pods" args: "nginx-pod app=web" # Set image operation: "set" resource: "image" args: "deployment/nginx nginx=nginx:latest"

Available in: readonly, readwrite, admin

Provides debugging and monitoring capabilities.

- operation: The operation to perform (logs, events, top, exec, cp)
- resource: The resource type or specific resource
- args: Additional arguments

# View logs operation: "logs" resource: "" args: "nginx-pod -f" # Execute command in pod operation: "exec" resource: "" args: "nginx-pod -- ls /app"

Available in: readonly, readwrite, admin

Provides cluster-level information and API discovery.

- operation: The operation to perform (cluster-info, api-resources, api-versions, explain)
- resource: For explain operation, the resource to document
- args: Additional flags

# Get cluster info operation: "cluster-info" resource: "" args: "" # Explain pod spec operation: "explain" resource: "pod.spec" args: "--recursive"

Available in: readonly, readwrite, admin

Handles configuration validation, security operations, and kubectl context management. In readonly mode, supportsdiff,auth can-i, and read-only config operations.

- operation: The operation to perform (diff, auth, certificate, config)
- resource: Subcommand for auth/certificate/config operations
- args: Operation-specific arguments

# Check permissions operation: "auth" resource: "can-i" args: "create pods" # Approve certificate operation: "certificate" resource: "approve" args: "csr-name" # Get current context operation: "config" resource: "current-context" args: "" # List all contexts operation: "config" resource: "get-contexts" args: "" # Switch context (readwrite/admin only) operation: "config" resource: "use-context" args: "my-cluster-context"

- current-context: Display the current context (readonly, readwrite, admin)
- get-contexts: List all available contexts (readonly, readwrite, admin)
- use-context: Switch to a different context (readwrite, admin only)

Available when:--additional-tools=helmis specified

Run Helm commands for managing Kubernetes applications.

command: "list --all-namespaces"

Available when:--additional-tools=ciliumis specified

Run Cilium commands for network policies and observability.

Available when:--additional-tools=hubbleis specified

Run Hubble commands for network monitoring and debugging in Cilium-enabled clusters.

command: "status" command: "observe observe --namespace backend-jobs --from-label 'app=web'" command: "list nodes"

To opt out, set the environment variableKUBERNETES_MCP_COLLECT_TELEMETRY=false.

The mcp-kubernetes server supports exporting telemetry data using OpenTelemetry Protocol (OTLP). You can configure an OTLP endpoint to send traces to any OpenTelemetry-compatible backend:

{ "mcpServers": { "kubernetes": { "command": "mcp-kubernetes", "args": ["--otlp-endpoint", "localhost:4317"] } } }

How to inspect MCP server requests and responses:

npx @modelcontextprotocol/inspector <path of binary 'mcp-kubernetes'>

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visithttps://cla.opensource.microsoft.com.

This project has adopted theMicrosoft Open Source Code of Conduct. For more information see theCode of Conduct FAQor contactopencode@microsoft.comwith any additional questions or comments.

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must followMicrosoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.

An MCP server that enables AI assistants to interact with and manage Kubernetes clusters.