Skip to content
Back to search

k8s-mcp-server

K8s-mcp-server is a Model Context Protocol (MCP) server that enables AI assistants like Claude to securely execute Kubernetes commands. It provides a bridge between language models and essential Kubernetes CLI tools including kubectl, helm, istioctl, and argocd, allowing AI systems to assist with cluster management, troubleshooting, and deployments

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/alexei-led--k8s-mcp-server/badge.svg)](/listings/alexei-led--k8s-mcp-server)

HTML

<a href="/listings/alexei-led--k8s-mcp-server"><img src="/api/listings/alexei-led--k8s-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Get Claude helping with your Kubernetes clusters in under 2 minutes:

1. **Create or update your Claude Desktop configuration file**: - **macOS**: Edit `$HOME/Library/Application Support/Claude/claude_desktop_config.json` - **Windows**: Edit `%APPDATA%\Claude\claude_desktop_config.json` - **Linux**: Edit `$HOME/.config/Claude/claude_desktop_config.json`

   {
     "mcpServers": {
       "kubernetes": {
         "command": "docker",
         "args": [
           "run",
           "-i",
           "--rm",
           "-v",
           "/Users/YOUR_USER_NAME/.kube:/home/appuser/.kube:ro",
           "ghcr.io/alexei-led/k8s-mcp-server:latest"
         ]
       }
     }
   }

2. **Restart Claude Desktop** - After restart, you'll see the Tools icon (🔨) in the bottom right of your input field - This indicates Claude can now access K8s tools via the MCP server

3. **Start using K8s tools directly in Claude Desktop**: - "What Kubernetes contexts do I have available?" - "Show me all pods in the default namespace" - "Create a deployment with 3 replicas of nginx:1.21" - "Explain what's wrong with my StatefulSet 'database' in namespace 'prod'" - "Deploy the bitnami/wordpress chart with Helm and set service type to LoadBalancer"

> **Note**: Claude Desktop will automatically route K8s commands through the MCP server, allowing natural conversation about your clusters without leaving the Claude interface.

> **Cloud Providers**: For AWS EKS, GKE, or Azure AKS, you'll need additional configuration. See the [Cloud Provider Support](./docs/cloud-providers.md) guide.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 260 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # K8s MCP Server
  2. [![CI Status](https://github.com/alexei-led/k8s-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/alexei-led/k8s-mcp-server/actions/workflows/ci.yml)
  3. [![Release Status](https://github.com/alexei-led/k8s-mcp-server/actions/workflows/release.yml/badge.svg)](https://github.com/alexei-led/k8s-mcp-server/actions/workflows/release.yml)
  4. [![codecov](https://codecov.io/gh/alexei-led/k8s-mcp-server/graph/badge.svg?token=eCaXPJ0olS)](https://codecov.io/gh/alexei-led/k8s-mcp-server)
  5. [![Image Tags](https://ghcr-badge.egpl.dev/alexei-led/k8s-mcp-server/tags?color=%2344cc11&ignore=latest&n=4&label=image+tags&trim=)](https://github.com/alexei-led/k8s-mcp-server/pkgs/container/k8s-mcp-server/versions)
  6. [![Image Size](https://ghcr-badge.egpl.dev/alexei-led/k8s-mcp-server/size?color=%2344cc11&tag=latest&label=image+size&trim=)](https://github.com/alexei-led/k8s-mcp-server/pkgs/container/k8s-mcp-server)
  7. [![Python Version](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
  8. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  9. K8s MCP Server is a Docker-based server implementing [Anthropic's Model Context Protocol (MCP)](https://www.anthropic.com/news/introducing-mcp) that enables Claude to run Kubernetes CLI tools (`kubectl`, `istioctl`, `helm`, `argocd`) in a secure, containerized environment.
  10. ## Demo: Deploy and Troubleshoot WordPress
  11. **Session 1:** Using k8s-mcp-server and Helm CLI to deploy a WordPress application in the claude-demo namespace, then intentionally breaking it by scaling the MariaDB StatefulSet to zero.
  12. **Session 2:** Troubleshooting session where we use k8s-mcp-server to diagnose the broken WordPress site through kubectl commands, identify the missing database issue, and fix it by scaling up the StatefulSet and configuring ingress access..
  13. [Demo](https://private-user-images.githubusercontent.com/1898375/428398164-5ddce5bc-ec92-459b-a506-5d4442618a81.mp4?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3NDMzNDE0OTEsIm5iZiI6MTc0MzM0MTE5MSwicGF0aCI6Ii8xODk4Mzc1LzQyODM5ODE2NC01ZGRjZTViYy1lYzkyLTQ1OWItYTUwNi01ZDQ0NDI2MThhODEubXA0P1gtQW16LUFsZ29yaXRobT1BV1M0LUhNQUMtU0hBMjU2JlgtQW16LUNyZWRlbnRpYWw9QUtJQVZDT0RZTFNBNTNQUUs0WkElMkYyMDI1MDMzMCUyRnVzLWVhc3QtMSUyRnMzJTJGYXdzNF9yZXF1ZXN0JlgtQW16LURhdGU9MjAyNTAzMzBUMTMyNjMxWiZYLUFtei1FeHBpcmVzPTMwMCZYLUFtei1TaWduYXR1cmU9YmUyNDExMGUzOGRlN2QxNWViMzhhOTE4Y2U1ZmRjMTQxYTI0OGNlNTFjNTRlMjFjNmQ3NTNhNGFmODNkODIzMSZYLUFtei1TaWduZWRIZWFkZXJzPWhvc3QifQ.hwKERwuQRXxHEYJ9d_fQ__XL1gj8l76nO6Yy6M4Uov8)
  14. ## How It Works
  15. ```mermaid
  16. flowchart LR
  17. A[User] --> |Asks K8s question| B[Claude]
  18. B --> |Sends command via MCP| C[K8s MCP Server]
  19. C --> |Executes kubectl, helm, etc.| D[Kubernetes Cluster]
  20. D --> |Returns results| C
  21. C --> |Returns formatted results| B
  22. B --> |Analyzes & explains| A
  23. ```
  24. Claude can help users by:
  25. - Explaining complex Kubernetes concepts
  26. - Running commands against your cluster
  27. - Troubleshooting issues
  28. - Suggesting optimizations
  29. - Crafting Kubernetes manifests
  30. ## Quick Start with Claude Desktop
  31. Get Claude helping with your Kubernetes clusters in under 2 minutes:
  32. 1. **Create or update your Claude Desktop configuration file**:
  33. - **macOS**: Edit `$HOME/Library/Application Support/Claude/claude_desktop_config.json`
  34. - **Windows**: Edit `%APPDATA%\Claude\claude_desktop_config.json`
  35. - **Linux**: Edit `$HOME/.config/Claude/claude_desktop_config.json`
  36. ```json
  37. {
  38. "mcpServers": {
  39. "kubernetes": {
  40. "command": "docker",
  41. "args": [
  42. "run",
  43. "-i",
  44. "--rm",
  45. "-v",
  46. "/Users/YOUR_USER_NAME/.kube:/home/appuser/.kube:ro",
  47. "ghcr.io/alexei-led/k8s-mcp-server:latest"
  48. ]
  49. }
  50. }
  51. }
  52. ```
  53. 2. **Restart Claude Desktop**
  54. - After restart, you'll see the Tools icon (🔨) in the bottom right of your input field
  55. - This indicates Claude can now access K8s tools via the MCP server
  56. 3. **Start using K8s tools directly in Claude Desktop**:
  57. - "What Kubernetes contexts do I have available?"
  58. - "Show me all pods in the default namespace"
  59. - "Create a deployment with 3 replicas of nginx:1.21"
  60. - "Explain what's wrong with my StatefulSet 'database' in namespace 'prod'"
  61. - "Deploy the bitnami/wordpress chart with Helm and set service type to LoadBalancer"
  62. > **Note**: Claude Desktop will automatically route K8s commands through the MCP server, allowing natural conversation about your clusters without leaving the Claude interface.
  63. > **Cloud Providers**: For AWS EKS, GKE, or Azure AKS, you'll need additional configuration. See the [Cloud Provider Support](./docs/cloud-providers.md) guide.
  64. ## Features
  65. - **Multiple Kubernetes Tools**: `kubectl`, `helm`, `istioctl`, and `argocd` in one container
  66. - **Cloud Providers**: Native support for AWS EKS, Google GKE, and Azure AKS
  67. - **Security**: Runs as non-root user with strict command validation
  68. - **Command Piping**: Support for common Unix tools like `jq`, `grep`, and `sed`
  69. - **Easy Configuration**: Simple environment variables for customization
  70. ## Transport Protocols
  71. The server supports three transport protocols, configured via `K8S_MCP_TRANSPORT`:
  72. | Transport | Description | Default |
  73. |-----------|-------------|---------|
  74. | `stdio` | Standard I/O (Claude Desktop default) | Yes |
  75. | `streamable-http` | HTTP transport (recommended for remote/web clients, MCP spec 2025-11-25) | No |
  76. | `sse` | Server-Sent Events (deprecated, use `streamable-http` instead) | No |
  77. Example using Streamable HTTP transport:
  78. ```bash
  79. docker run --rm -p 8000:8000 \
  80. -v ~/.kube:/home/appuser/.kube:ro \
  81. -e K8S_MCP_TRANSPORT=streamable-http \
  82. ghcr.io/alexei-led/k8s-mcp-server:latest
  83. ```
  84. > **Note**: When running in Docker with HTTP transports, the server automatically binds to `0.0.0.0` for proper port mapping. Outside Docker it binds to `127.0.0.1`.
  85. ## Documentation
  86. - [Getting Started Guide](./docs/getting-started.md) - Detailed setup instructions
  87. - [Cloud Provider Support](./docs/cloud-providers.md) - EKS, GKE, and AKS configuration
  88. - [Supported Tools](./docs/supported-tools.md) - Complete list of all included CLI tools
  89. - [Environment Variables](./docs/environment-variables.md) - Configuration options
  90. - [Security Features](./docs/security.md) - Security modes and custom rules
  91. - [Claude Integration](./docs/claude-integration.md) - Detailed Claude Desktop setup
  92. - [Architecture](./docs/architecture.md) - System architecture and components
  93. - [Detailed Specification](./docs/spec.md) - Complete technical specification
  94. ## Usage Examples
  95. Once connected, you can ask Claude to help with Kubernetes tasks using natural language:
  96. ```mermaid
  97. flowchart TB
  98. subgraph "Basic Commands"
  99. A1["Show me all pods in the default namespace"]
  100. A2["Get all services across all namespaces"]
  101. A3["Display the logs for the nginx pod"]
  102. end
  103. subgraph "Troubleshooting"
  104. B1["Why is my deployment not starting?"]
  105. B2["Describe the failing pod and explain the error"]
  106. B3["Check if my service is properly connected to the pods"]
  107. end
  108. subgraph "Deployments & Configuration"
  109. C1["Deploy the Nginx Helm chart"]
  110. C2["Create a deployment with 3 replicas of nginx:latest"]
  111. C3["Set up an ingress for my service"]
  112. end
  113. subgraph "Advanced Operations"
  114. D1["Check the status of my Istio service mesh"]
  115. D2["Set up a canary deployment with 20% traffic to v2"]
  116. D3["Create an ArgoCD application for my repo"]
  117. end
  118. ```
  119. Claude can understand your intent and run the appropriate kubectl, helm, istioctl, or argocd commands based on your request. It can then explain the output in simple terms or help you troubleshoot issues.
  120. ## Advanced Claude Desktop Configuration
  121. Configure Claude Desktop to optimize your Kubernetes workflow:
  122. ### Target Specific Clusters and Namespaces
  123. ```json
  124. {
  125. "mcpServers": {
  126. "kubernetes": {
  127. "command": "docker",
  128. "args": [
  129. "run", "-i", "--rm",
  130. "-v", "/Users/YOUR_USER_NAME/.kube:/home/appuser/.kube:ro",
  131. "-e", "K8S_CONTEXT=production-cluster",
  132. "-e", "K8S_NAMESPACE=my-application",
  133. "-e", "K8S_MCP_TIMEOUT=600",
  134. "ghcr.io/alexei-led/k8s-mcp-server:latest"
  135. ]
  136. }
  137. }
  138. }
  139. ```
  140. ### Connect to AWS EKS Clusters
  141. ```json
  142. {
  143. "mcpServers": {
  144. "kubernetes": {
  145. "command": "docker",
  146. "args": [
  147. "run", "-i", "--rm",
  148. "-v", "/Users/YOUR_USER_NAME/.kube:/home/appuser/.kube:ro",
  149. "-v", "/Users/YOUR_USER_NAME/.aws:/home/appuser/.aws:ro",
  150. "-e", "AWS_PROFILE=production",
  151. "-e", "AWS_REGION=us-west-2",
  152. "ghcr.io/alexei-led/k8s-mcp-server:latest"
  153. ]
  154. }
  155. }
  156. }
  157. ```
  158. ### Connect to Google GKE Clusters
  159. ```json
  160. {
  161. "mcpServers": {
  162. "kubernetes": {
  163. "command": "docker",
  164. "args": [
  165. "run", "-i", "--rm",
  166. "-v", "/Users/YOUR_USER_NAME/.kube:/home/appuser/.kube:ro",
  167. "-v", "/Users/YOUR_USER_NAME/.config/gcloud:/home/appuser/.config/gcloud:ro",
  168. "-e", "CLOUDSDK_CORE_PROJECT=my-gcp-project",
  169. "-e", "CLOUDSDK_COMPUTE_REGION=us-central1",
  170. "ghcr.io/alexei-led/k8s-mcp-server:latest"
  171. ]
  172. }
  173. }
  174. }
  175. ```
  176. ### Connect to Azure AKS Clusters
  177. ```json
  178. {
  179. "mcpServers": {
  180. "kubernetes": {
  181. "command": "docker",
  182. "args": [
  183. "run", "-i", "--rm",
  184. "-v", "/Users/YOUR_USER_NAME/.kube:/home/appuser/.kube:ro",
  185. "-v", "/Users/YOUR_USER_NAME/.azure:/home/appuser/.azure:ro",
  186. "-e", "AZURE_SUBSCRIPTION=my-subscription-id",
  187. "ghcr.io/alexei-led/k8s-mcp-server:latest"
  188. ]
  189. }
  190. }
  191. }
  192. ```
  193. ### Permissive Security Mode
  194. ```json
  195. {
  196. "mcpServers": {
  197. "kubernetes": {
  198. "command": "docker",
  199. "args": [
  200. "run", "-i", "--rm",
  201. "-v", "/Users/YOUR_USER_NAME/.kube:/home/appuser/.kube:ro",
  202. "-e", "K8S_MCP_SECURITY_MODE=permissive",
  203. "ghcr.io/alexei-led/k8s-mcp-server:latest"
  204. ]
  205. }
  206. }
  207. }
  208. ```
  209. > For detailed security configuration options, see [Security Documentation](./docs/security.md).
  210. ## License
  211. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.