Skip to content
Back to search

k8s-mcp-server

Manage Your Kubernetes Cluster with k8s mcp-server

Safety scan

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

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/reza-gholizade/k8s-mcp-server with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/reza-gholizade/k8s-mcp-server'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

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

HTML

<a href="/listings/reza-gholizade--k8s-mcp-server"><img src="/api/listings/reza-gholizade--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.

1. **Clone the repository:** ```bash git clone https://github.com/reza-gholizade/k8s-mcp-server.git cd k8s-mcp-server ```

2. **Install dependencies:** ```bash go mod download ```

3. **Build the server:** ```bash go build -o k8s-mcp-server . ```

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 · 1,094 lines

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

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Kubernetes MCP Server
  2. A Kubernetes Model Context Protocol (MCP) server that provides tools for interacting with Kubernetes clusters through a standardized interface.
  3. ## Hosted deployment
  4. A hosted deployment is available on [Fronteir AI](https://fronteir.ai/mcp/reza-gholizade-k8s-mcp-server).
  5. ## Features
  6. - **API Resource Discovery**: Get all available API resources in your Kubernetes cluster.
  7. - **Resource Listing**: List resources of any type with optional namespace and label filtering.
  8. - **Resource Details**: Get detailed information about specific Kubernetes resources.
  9. - **Resource Description**: Get comprehensive descriptions of Kubernetes resources, similar to `kubectl describe`.
  10. - **Pod Logs**: Retrieve logs from specific pods (optionally from a specific container, or all containers if unspecified).
  11. - **Node Metrics**: Get resource usage metrics for specific nodes.
  12. - **Pod Metrics**: Get CPU and Memory metrics for specific pods.
  13. - **Event Listing**: List events within a namespace or for a specific resource.
  14. - **Resource Creation/Updating**: Create new Kubernetes resources or update existing ones from a YAML or JSON manifest.
  15. - **Resource Deletion**: It deletes a resource in the Kubernetes cluster based on the provided namespace and kind.
  16. - **Standardized Interface**: Uses the MCP protocol for consistent tool interaction.
  17. - **Flexible Configuration**: Supports different Kubernetes contexts and resource scopes.
  18. - **Multiple Modes**: Run in `stdio` mode for CLI tools, `sse` mode, or `streamable-http` mode for web applications, and `--readonly` for no change in the cluster.
  19. - **Security**: Runs as non-root user in Docker containers for enhanced security.
  20. ## Prerequisites
  21. - Go 1.23 or later
  22. - Access to a Kubernetes cluster
  23. - `kubectl` configured with appropriate cluster access
  24. ## Installation
  25. 1. **Clone the repository:**
  26. ```bash
  27. git clone https://github.com/reza-gholizade/k8s-mcp-server.git
  28. cd k8s-mcp-server
  29. ```
  30. 2. **Install dependencies:**
  31. ```bash
  32. go mod download
  33. ```
  34. 3. **Build the server:**
  35. ```bash
  36. go build -o k8s-mcp-server .
  37. ```
  38. ## Usage
  39. ### Starting the Server
  40. The server can run in three modes, configurable via command-line flags or environment variables.
  41. #### Stdio Mode (for CLI integrations)
  42. This mode uses standard input/output for communication.
  43. ```bash
  44. ./k8s-mcp-server --mode stdio
  45. ```
  46. Or using environment variables:
  47. ```bash
  48. SERVER_MODE=stdio ./k8s-mcp-server
  49. ```
  50. #### SSE Mode (for web applications)
  51. This mode starts an HTTP server with Server-Sent Events support.
  52. HTTP transports require a bearer token and listen on loopback by default:
  53. ```bash
  54. MCP_AUTH_TOKEN="$(openssl rand -hex 32)" ./k8s-mcp-server --mode sse
  55. ```
  56. Specify a port:
  57. ```bash
  58. MCP_AUTH_TOKEN="your-random-secret" ./k8s-mcp-server --mode sse --port 9090
  59. ```
  60. Or using environment variables:
  61. ```bash
  62. SERVER_MODE=sse SERVER_PORT=9090 MCP_AUTH_TOKEN="your-random-secret" ./k8s-mcp-server
  63. ```
  64. #### Streamable-HTTP Mode (for web applications)
  65. This mode starts an HTTP server with streamable-http transport support, following the MCP specification.
  66. Default (port 8080):
  67. ```bash
  68. MCP_AUTH_TOKEN="your-random-secret" ./k8s-mcp-server --mode streamable-http
  69. ```
  70. Specify a port:
  71. ```bash
  72. MCP_AUTH_TOKEN="your-random-secret" ./k8s-mcp-server --mode streamable-http --port 9090
  73. ```
  74. Or using environment variables:
  75. ```bash
  76. SERVER_MODE=streamable-http SERVER_PORT=9090 MCP_AUTH_TOKEN="your-random-secret" ./k8s-mcp-server
  77. ```
  78. The server will be available at `http://localhost:8080/mcp` (or your specified port).
  79. If no mode is specified, the server defaults to `stdio`. HTTP modes bind to
  80. `127.0.0.1` by default. Set `SERVER_HOST=0.0.0.0` (or `--host 0.0.0.0`) only
  81. when network access is intentional, and send `Authorization: Bearer <token>`
  82. on every MCP request. Browser clients must also be explicitly allowed with a
  83. comma-separated `MCP_ALLOWED_ORIGINS` value.
  84. The unauthenticated `/healthz` endpoint is available for container health checks;
  85. it does not expose MCP functionality.
  86. ### Kubernetes Authentication
  87. The server supports multiple authentication methods, which are tried in the following order of priority:
  88. #### 1. Kubeconfig Content from Environment Variable
  89. You can provide the entire kubeconfig file content via the `KUBECONFIG_DATA` environment variable:
  90. ```bash
  91. export KUBECONFIG_DATA="$(cat ~/.kube/config)"
  92. ./k8s-mcp-server
  93. ```
  94. This is useful when you want to avoid mounting files or when running in environments where file access is restricted.
  95. #### 2. API Server URL and Token
  96. You can authenticate using a Kubernetes API server URL and bearer token:
  97. ```bash
  98. export KUBERNETES_SERVER="https://kubernetes.example.com:6443"
  99. export KUBERNETES_TOKEN="your-bearer-token-here"
  100. ./k8s-mcp-server
  101. ```
  102. Optional environment variables for TLS configuration:
  103. - `KUBERNETES_CA_CERT`: CA certificate content (base64-encoded or PEM format)
  104. - `KUBERNETES_CA_CERT_PATH`: Path to CA certificate file
  105. - `KUBERNETES_INSECURE`: Set to `"true"` to skip TLS verification (not recommended for production)
  106. Example with CA certificate:
  107. ```bash
  108. export KUBERNETES_SERVER="https://kubernetes.example.com:6443"
  109. export KUBERNETES_TOKEN="your-bearer-token-here"
  110. export KUBERNETES_CA_CERT_PATH="/path/to/ca.crt"
  111. ./k8s-mcp-server
  112. ```
  113. #### 3. In-Cluster Authentication (Service Account)
  114. When running inside a Kubernetes cluster, the server automatically detects and uses the service account token from `/var/run/secrets/kubernetes.io/serviceaccount/token`. This is the recommended method for running the server as a pod within a cluster.
  115. **Example Deployment:**
  116. ```yaml
  117. apiVersion: v1
  118. kind: ServiceAccount
  119. metadata:
  120. name: k8s-mcp-server-sa
  121. namespace: default
  122. ---
  123. apiVersion: rbac.authorization.k8s.io/v1
  124. kind: ClusterRole
  125. metadata:
  126. name: k8s-mcp-server-role
  127. rules:
  128. - apiGroups: [""]
  129. resources: ["*"]
  130. verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
  131. - apiGroups: ["apps"]
  132. resources: ["*"]
  133. verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
  134. # Add more rules as needed for your use case
  135. ---
  136. apiVersion: rbac.authorization.k8s.io/v1
  137. kind: ClusterRoleBinding
  138. metadata:
  139. name: k8s-mcp-server-rb
  140. subjects:
  141. - kind: ServiceAccount
  142. name: k8s-mcp-server-sa
  143. namespace: default
  144. roleRef:
  145. kind: ClusterRole
  146. name: k8s-mcp-server-role
  147. apiGroup: rbac.authorization.k8s.io
  148. ---
  149. apiVersion: apps/v1
  150. kind: Deployment
  151. metadata:
  152. name: k8s-mcp-server
  153. namespace: default
  154. spec:
  155. replicas: 1
  156. selector:
  157. matchLabels:
  158. app: k8s-mcp-server
  159. template:
  160. metadata:
  161. labels:
  162. app: k8s-mcp-server
  163. spec:
  164. serviceAccountName: k8s-mcp-server-sa
  165. containers:
  166. - name: k8s-mcp-server
  167. image: ginnux/k8s-mcp-server:latest
  168. ports:
  169. - containerPort: 8080
  170. env:
  171. - name: SERVER_MODE
  172. value: "sse"
  173. - name: SERVER_PORT
  174. value: "8080"
  175. ```
  176. #### 4. Kubeconfig File Path (Default)
  177. If none of the above methods are available, the server falls back to using a kubeconfig file:
  178. - Uses the path provided via `--kubeconfig` flag (if implemented) or `KUBECONFIG` environment variable
  179. - Defaults to `~/.kube/config` if neither is specified
  180. ```bash
  181. # Using default ~/.kube/config
  182. ./k8s-mcp-server
  183. # Using custom kubeconfig path
  184. export KUBECONFIG=/path/to/your/kubeconfig
  185. ./k8s-mcp-server
  186. ```
  187. **Note:** The server automatically detects which authentication method to use based on the available environment variables and file system. You don't need to explicitly configure the authentication method - it will use the first available method in the priority order listed above.
  188. #### Read-Only Mode
  189. The server supports a read-only mode that disables all write operations, providing a safer way to explore and monitor your Kubernetes cluster without the risk of making changes.
  190. Enable read-only mode with the `--read-only` flag:
  191. ```bash
  192. ./k8s-mcp-server --read-only
  193. ```
  194. You can combine read-only mode with any server mode:
  195. ```bash
  196. # Read-only with stdio mode
  197. ./k8s-mcp-server --mode stdio --read-only
  198. # Read-only with SSE mode
  199. ./k8s-mcp-server --mode sse --read-only
  200. # Read-only with streamable-http mode
  201. ./k8s-mcp-server --mode streamable-http --read-only
  202. ```
  203. When read-only mode is enabled, the following tools are disabled:
  204. - `createResource` (Kubernetes resource creation/updates)
  205. - `helmInstall` (Helm chart installations)
  206. - `helmUpgrade` (Helm chart upgrades)
  207. - `helmUninstall` (Helm chart uninstallations)
  208. - `helmRollback` (Helm release rollbacks)
  209. - `helmRepoAdd` (Helm repository additions)
  210. All other read-only operations remain available, including listing resources, getting logs, viewing metrics, and inspecting Helm releases.
  211. #### Tool Category Flags
  212. You can selectively disable entire categories of tools using these flags:
  213. **Disable Kubernetes Tools:**
  214. ```bash
  215. ./k8s-mcp-server --no-k8s
  216. ```
  217. **Disable Helm Tools:**
  218. ```bash
  219. ./k8s-mcp-server --no-helm
  220. ```
  221. **Combine with other flags:**
  222. ```bash
  223. # Read-only mode with only Kubernetes tools (no Helm)
  224. ./k8s-mcp-server --read-only --no-helm
  225. # Read-only mode with only Helm tools (no Kubernetes)
  226. ./k8s-mcp-server --read-only --no-k8s
  227. # SSE mode with only Kubernetes tools
  228. ./k8s-mcp-server --mode sse --no-helm
  229. ```
  230. **Note:** You cannot use both `--no-k8s` and `--no-helm` together, as this would result in no available tools. The server will exit with an error if both flags are provided.
  231. When `--no-k8s` is enabled, all Kubernetes tools are disabled:
  232. - `getAPIResources`, `listResources`, `getResource`, `describeResource`
  233. - `getPodsLogs`, `getNodeMetrics`, `getPodMetrics`, `getEvents`
  234. - `createResource` (if not in read-only mode)
  235. When `--no-helm` is enabled, all Helm tools are disabled:
  236. - `helmList`, `helmGet`, `helmHistory`, `helmRepoList`
  237. - `helmInstall`, `helmUpgrade`, `helmUninstall`, `helmRollback`, `helmRepoAdd` (if not in read-only mode)
  238. ### Using the Docker Image
  239. You can also run the server using the pre-built Docker image from Docker Hub.
  240. 1. **Pull the image:**
  241. ```bash
  242. docker pull ginnux/k8s-mcp-server:latest
  243. ```
  244. You can replace `latest` with a specific version tag (e.g., `1.0.0`).
  245. 2. **Run the container:**
  246. **Note:** The server supports multiple authentication methods. You can either mount a kubeconfig file (as shown below) or use environment variables for authentication (see [Kubernetes Authentication](#kubernetes-authentication) section above).
  247. * **SSE Mode (default behavior of the image):**
  248. ```bash
  249. docker run -p 8080:8080 -v ~/.kube/config:/home/appuser/.kube/config:ro ginnux/k8s-mcp-server:latest
  250. ```
  251. This maps port 8080 of the container to port 8080 on your host and mounts your Kubernetes config read-only to the non-root user's home directory. The server will be available at `http://localhost:8080`. The image defaults to `sse` mode on port `8080`.
  252. * **Streamable-HTTP Mode:**
  253. ```bash
  254. docker run -p 8080:8080 -v ~/.kube/config:/home/appuser/.kube/config:ro ginnux/k8s-mcp-server:latest --mode streamable-http
  255. ```
  256. This runs the server in streamable-http mode. The server will be available at `http://localhost:8080/mcp`.
  257. * **Stdio Mode:**
  258. ```bash
  259. docker run -i --rm -v ~/.kube/config:/home/appuser/.kube/config:ro ginnux/k8s-mcp-server:latest --mode stdio
  260. ```
  261. The `-i` flag is important for interactive stdio communication. `--rm` cleans up the container after exit.
  262. * **Custom Port for SSE Mode:**
  263. ```bash
  264. docker run -p 9090:9090 -v ~/.kube/config:/home/appuser/.kube/config:ro ginnux/k8s-mcp-server:latest --mode sse --port 9090
  265. ```
  266. * **Custom Port for Streamable-HTTP Mode:**
  267. ```bash
  268. docker run -p 9090:9090 -v ~/.kube/config:/home/appuser/.kube/config:ro ginnux/k8s-mcp-server:latest --mode streamable-http --port 9090
  269. ```
  270. * **Alternative: Mount entire .kube directory:**
  271. ```bash
  272. docker run -p 8080:8080 -v ~/.kube:/home/appuser/.kube:ro ginnux/k8s-mcp-server:latest
  273. ```
  274. * **Using environment variables for authentication (no file mounting required):**
  275. ```bash
  276. # Using kubeconfig content from environment variable
  277. docker run -p 8080:8080 \
  278. -e KUBECONFIG_DATA="$(cat ~/.kube/config)" \
  279. ginnux/k8s-mcp-server:latest
  280. # Or using API server URL and token
  281. docker run -p 8080:8080 \
  282. -e KUBERNETES_SERVER="https://kubernetes.example.com:6443" \
  283. -e KUBERNETES_TOKEN="your-token-here" \
  284. -e KUBERNETES_CA_CERT_PATH="/path/to/ca.crt" \
  285. -v /path/to/ca.crt:/path/to/ca.crt:ro \
  286. ginnux/k8s-mcp-server:latest
  287. ```
  288. #### Using with Docker Compose
  289. Create a `docker-compose.yml` file:
  290. **Option 1: Using kubeconfig file (traditional method):**
  291. ```yaml
  292. version: '3.8'
  293. services:
  294. k8s-mcp-server:
  295. image: ginnux/k8s-mcp-server:latest # Or a specific version
  296. container_name: k8s-mcp-server
  297. ports:
  298. - "8080:8080" # Host:Container, adjust if using a different SERVER_PORT
  299. volumes:
  300. - ~/.kube:/home/appuser/.kube:ro # Mount kubeconfig read-only to non-root user home
  301. environment:
  302. - KUBECONFIG=/home/appuser/.kube/config
  303. - SERVER_MODE=sse # Can be 'stdio', 'sse', or 'streamable-http'
  304. - SERVER_PORT=8080 # Port for SSE/streamable-http modes
  305. # command: ["--read-only"] # Uncomment this line to enable read-only mode
  306. restart: unless-stopped
  307. healthcheck:
  308. test: ["CMD", "curl", "-f", "http://localhost:8080/"]
  309. interval: 30s
  310. timeout: 10s
  311. retries: 3
  312. start_period: 10s
  313. ```
  314. **Option 2: Using environment variables (no file mounting):**
  315. ```yaml
  316. version: '3.8'
  317. services:
  318. k8s-mcp-server:
  319. image: ginnux/k8s-mcp-server:latest
  320. container_name: k8s-mcp-server
  321. ports:
  322. - "8080:8080"
  323. environment:
  324. - KUBECONFIG_DATA=${KUBECONFIG_DATA} # Set this in your .env file or shell
  325. # Or use API server and token:
  326. # - KUBERNETES_SERVER=https://kubernetes.example.com:6443
  327. # - KUBERNETES_TOKEN=${KUBERNETES_TOKEN}
  328. - SERVER_MODE=sse
  329. - SERVER_PORT=8080
  330. restart: unless-stopped
  331. healthcheck:
  332. test: ["CMD", "curl", "-f", "http://localhost:8080/"]
  333. interval: 30s
  334. timeout: 10s
  335. retries: 3
  336. start_period: 10s
  337. ```
  338. **Note:** To enable read-only mode, use the `command` override as shown in Option 1. For stdio mode, you might need to adjust 'ports', add 'stdin_open: true' and 'tty: true', and potentially override the command.
  339. Then start with:
  340. ```bash
  341. docker compose up -d
  342. ```
  343. To see logs: `docker compose logs -f k8s-mcp-server`.
  344. #### Security Considerations
  345. The Docker image runs as a non-root user (`appuser` with UID 1001) for enhanced security:
  346. - The application binary is located at `/usr/local/bin/k8s-mcp-server`
  347. - The kubeconfig should be mounted to `/home/appuser/.kube/config`
  348. - Health checks are enabled to monitor container status
  349. - The container includes minimal dependencies (ca-certificates and curl only)
  350. SSE and streamable HTTP are fail-closed unless `MCP_AUTH_TOKEN` is set. Never
  351. publish an HTTP transport without authentication. Prefer `stdio` for local MCP
  352. clients, use `--read-only` where possible, and grant the server's Kubernetes
  353. identity only the RBAC permissions it needs. A session ID is not an authentication
  354. credential. Put remotely accessible deployments behind TLS and an authenticating
  355. reverse proxy, and configure `MCP_ALLOWED_ORIGINS` for browser-based clients.
  356. #### Making API Calls (SSE/Streamable-HTTP Mode)
  357. Once the server is running in SSE or streamable-http mode, you can make JSON-RPC calls to its HTTP endpoint:
  358. ```bash
  359. curl -X POST -H "Content-Type: application/json" -d '{
  360. "jsonrpc": "2.0",
  361. "id": 1,
  362. "method": "tools/call",
  363. "params": {
  364. "name": "getAPIResources",
  365. "arguments": {
  366. "includeNamespaceScoped": true,
  367. "includeClusterScoped": true
  368. }
  369. }
  370. }' http://localhost:8080/
  371. ```
  372. You can also check the health status:
  373. ```bash
  374. curl -f http://localhost:8080/
  375. ```
  376. ### Available Tools
  377. #### 1. `getAPIResources`
  378. Retrieves all available API resources in the Kubernetes cluster.
  379. **Parameters:**
  380. - `includeNamespaceScoped` (boolean, optional): Whether to include namespace-scoped resources (defaults to true).
  381. - `includeClusterScoped` (boolean, optional): Whether to include cluster-scoped resources (defaults to true).
  382. **Example:**
  383. ```json
  384. {
  385. "jsonrpc": "2.0",
  386. "id": 1,
  387. "method": "tools/call",
  388. "params": {
  389. "name": "getAPIResources",
  390. "arguments": {
  391. "includeNamespaceScoped": true,
  392. "includeClusterScoped": true
  393. }
  394. }
  395. }
  396. ```
  397. #### 2. `listResources`
  398. Lists all instances of a specific resource type.
  399. **Parameters:**
  400. - `Kind` (string, required): The kind of resource to list (e.g., "Pod", "Deployment").
  401. - `namespace` (string, optional): The namespace to list resources from. If omitted, lists across all namespaces for namespaced resources (subject to RBAC).
  402. - `labelSelector` (string, optional): Filter resources by label selector (e.g., "app=nginx,env=prod").
  403. **Example:**
  404. ```json
  405. {
  406. "jsonrpc": "2.0",
  407. "id": 1,
  408. "method": "tools/call",
  409. "params": {
  410. "name": "listResources",
  411. "arguments": {
  412. "Kind": "Pod",
  413. "namespace": "default",
  414. "labelSelector": "app=nginx"
  415. }
  416. }
  417. }
  418. ```
  419. #### 3. `getResource`
  420. Retrieves detailed information about a specific resource.
  421. **Parameters:**
  422. - `kind` (string, required): The kind of resource to get (e.g., "Pod", "Deployment").
  423. - `name` (string, required): The name of the resource to get.
  424. - `namespace` (string, optional): The namespace of the resource (required for namespaced resources).
  425. **Example:**
  426. ```json
  427. {
  428. "jsonrpc": "2.0",
  429. "id": 1,
  430. "method": "tools/call",
  431. "params": {
  432. "name": "getResource",
  433. "arguments": {
  434. "kind": "Pod",
  435. "name": "nginx-pod",
  436. "namespace": "default"
  437. }
  438. }
  439. }
  440. ```
  441. #### 4. `describeResource`
  442. Describes a resource in the Kubernetes cluster, similar to `kubectl describe`.
  443. **Parameters:**
  444. - `Kind` (string, required): The kind of resource to describe (e.g., "Pod", "Deployment").
  445. - `name` (string, required): The name of the resource to describe.
  446. - `namespace` (string, optional): The namespace of the resource (required for namespaced resources).
  447. **Example:**
  448. ```json
  449. {
  450. "jsonrpc": "2.0",
  451. "id": 1,
  452. "method": "tools/call",
  453. "params": {
  454. "name": "describeResource",
  455. "arguments": {
  456. "Kind": "Pod",
  457. "name": "nginx-pod",
  458. "namespace": "default"
  459. }
  460. }
  461. }
  462. ```
  463. #### 5. `getPodsLogs`
  464. Retrieves the logs of a specific pod.
  465. **Parameters:**
  466. - `Name` (string, required): The name of the pod.
  467. - `namespace` (string, required): The namespace of the pod.
  468. - `containerName` (string, optional): The specific container name within the pod. If omitted:
  469. - If the pod has one container, its logs are fetched.
  470. - If the pod has multiple containers, logs from all containers are fetched and concatenated.
  471. **Example:**
  472. ```json
  473. {
  474. "jsonrpc": "2.0",
  475. "id": 1,
  476. "method": "tools/call",
  477. "params": {
  478. "name": "getPodsLogs",
  479. "arguments": {
  480. "Name": "my-app-pod-12345",
  481. "namespace": "production",
  482. "containerName": "main-container"
  483. }
  484. }
  485. }
  486. ```
  487. #### 6. `getNodeMetrics`
  488. Retrieves resource usage metrics for a specific node.
  489. **Parameters:**
  490. - `Name` (string, required): The name of the node.
  491. **Example:**
  492. ```json
  493. {
  494. "jsonrpc": "2.0",
  495. "id": 1,
  496. "method": "tools/call",
  497. "params": {
  498. "name": "getNodeMetrics",
  499. "arguments": {
  500. "Name": "worker-node-1"
  501. }
  502. }
  503. }
  504. ```
  505. #### 7. `getPodMetrics`
  506. Retrieves CPU and Memory metrics for a specific pod.
  507. **Parameters:**
  508. - `namespace` (string, required): The namespace of the pod.
  509. - `podName` (string, required): The name of the pod.
  510. **Example:**
  511. ```json
  512. {
  513. "jsonrpc": "2.0",
  514. "id": 1,
  515. "method": "tools/call",
  516. "params": {
  517. "name": "getPodMetrics",
  518. "arguments": {
  519. "namespace": "default",
  520. "podName": "my-app-pod-67890"
  521. }
  522. }
  523. }
  524. ```
  525. #### 8. `getEvents`
  526. Retrieves events for a specific namespace or resource.
  527. **Parameters:**
  528. - `namespace` (string, optional): The namespace to get events from. If omitted, events from all namespaces are considered (subject to RBAC).
  529. - `resourceName` (string, optional): The name of a specific resource (e.g., a Pod name) to filter events for.
  530. - `resourceKind` (string, optional): The kind of the specific resource (e.g., "Pod") if `resourceName` is provided.
  531. **Example (Namespace Events):**
  532. ```json
  533. {
  534. "jsonrpc": "2.0",
  535. "id": 1,
  536. "method": "tools/call",
  537. "params": {
  538. "name": "getEvents",
  539. "arguments": {
  540. "namespace": "default"
  541. }
  542. }
  543. }
  544. ```
  545. **Example (Resource Events):**
  546. ```json
  547. {
  548. "jsonrpc": "2.0",
  549. "id": 1,
  550. "method": "tools/call",
  551. "params": {
  552. "name": "getEvents",
  553. "arguments": {
  554. "namespace": "production",
  555. "resourceName": "my-app-pod-12345",
  556. "resourceKind": "Pod"
  557. }
  558. }
  559. }
  560. ```
  561. #### 9. `createOrUpdateResource`
  562. Creates a new resource or updates an existing one from a JSON manifest.
  563. **Parameters:**
  564. - `manifest` (string, required): The JSON manifest of the resource.
  565. - `namespace` (string, optional): The namespace in which to create/update the resource. If the manifest contains a namespace, this parameter can be used to override it. If not provided and the manifest doesn't specify one, "default" might be assumed or it might be an error depending on the resource type.
  566. **Example:**
  567. ```json
  568. {
  569. "jsonrpc": "2.0",
  570. "id": 1,
  571. "method": "tools/call",
  572. "params": {
  573. "name": "createResource",
  574. "arguments": {
  575. "kind": "Deployment",
  576. "namespace": "default",
  577. "manifest": "{\"apiVersion\":\"apps/v1\",\"kind\":\"Deployment\",\"metadata\":{\"name\":\"nginx-deployment\"},\"spec\":{\"replicas\":1,\"selector\":{\"matchLabels\":{\"app\":\"nginx\"}},\"template\":{\"metadata\":{\"labels\":{\"app\":\"nginx\"}},\"spec\":{\"containers\":[{\"name\":\"nginx\",\"image\":\"nginx:latest\"}]}}}}"
  578. }
  579. }
  580. }
  581. ```
  582. #### 10. `createResourceYAML`
  583. Creates a new resource or updates an existing one from a YAML manifest. This tool is specifically optimized for YAML input and provides better error handling for YAML parsing issues.
  584. **Parameters:**
  585. - `yamlManifest` (string, required): The YAML manifest of the resource.
  586. - `namespace` (string, optional): The namespace in which to create/update the resource. If the manifest contains a namespace, this parameter can be used to override it. If not provided and the manifest doesn't specify one, "default" might be assumed or it might be an error depending on the resource type.
  587. - `kind` (string, optional): The kind of the resource. If not provided, the kind will be inferred from the YAML manifest.
  588. **Example:**
  589. ```json
  590. {
  591. "jsonrpc": "2.0",
  592. "id": 1,
  593. "method": "tools/call",
  594. "params": {
  595. "name": "createResourceYAML",
  596. "arguments": {
  597. "namespace": "default",
  598. "yamlManifest": "apiVersion: v1\nkind: Pod\nmetadata:\n name: my-new-pod\nspec:\n containers:\n - name: nginx\n image: nginx:latest"
  599. }
  600. }
  601. }
  602. ```
  603. #### 11. `rolloutRestart`
  604. Triggers a rolling restart of a Kubernetes resource that supports spec.template.metadata.annotations. This includes Deployment, DaemonSet, StatefulSet, Job, and similar resources.
  605. **Parameters:**
  606. - `kind` (string, required): The kind of resource (e.g., "Deployment", "StatefulSet").
  607. - `name`: (string, required): The name of the resource to restart.
  608. - `namespace` (string, required for namespaced resources): The namespace of the resource.
  609. **Example (StatefulSet):**
  610. ```json
  611. {
  612. "jsonrpc": "2.0",
  613. "id": 1,
  614. "method": "tools/call",
  615. "params": {
  616. "name": "rolloutRestart",
  617. "arguments": {
  618. "kind": "StatefulSet",
  619. "name": "redis-cluster-01",
  620. "namespace": "default"
  621. }
  622. }
  623. }
  624. ```
  625. **Example (Deployment):**
  626. ```json
  627. {
  628. "jsonrpc": "2.0",
  629. "id": 2,
  630. "method": "tools/call",
  631. "params": {
  632. "name": "rolloutRestart",
  633. "arguments": {
  634. "kind": "Deployment",
  635. "name": "my-app-deployment",
  636. "namespace": "default"
  637. }
  638. }
  639. }
  640. ```
  641. #### 12. `deleteResource`
  642. Deletes a specific resource from the Kubernetes cluster.
  643. **Parameters:**
  644. - `kind` (string, required): The type of resource to delete.
  645. - `name` (string, required): The name of the resource to delete.
  646. - `namespace` (string, optional): The namespace of the resource (required for namespaced resources).
  647. **Example:**
  648. ```json
  649. {
  650. "jsonrpc": "2.0",
  651. "id": 1,
  652. "method": "tools/call",
  653. "params": {
  654. "name": "deleteResource",
  655. "arguments": {
  656. "kind": "Pod",
  657. "name": "my-pod",
  658. "namespace": "default"
  659. }
  660. }
  661. }
  662. ```
  663. #### 13. `getIngresses`
  664. Retrieves ingress resources from the Kubernetes cluster.
  665. You can filter ingresses by host. If no host is provided, all ingresses are returned.
  666. **Parameters:**
  667. - `host` (string, optional): The host to filter ingresses by. If omitted, all ingresses are included.
  668. **Example:**
  669. ```json
  670. {
  671. "jsonrpc": "2.0",
  672. "id": 1,
  673. "method": "tools/call",
  674. "params": {
  675. "name": "getIngresses",
  676. "arguments": {
  677. "host": "example.com"
  678. }
  679. }
  680. }
  681. ```
  682. ### Helm Operations
  683. #### 14. `helmInstall`
  684. Install a Helm chart to the Kubernetes cluster.
  685. **Parameters:**
  686. - `releaseName` (string, required): Name of the Helm release
  687. - `chartName` (string, required): Name or path of the Helm chart
  688. - `namespace` (string, optional): Kubernetes namespace for the release (defaults to "default")
  689. - `repoURL` (string, optional): Helm repository URL
  690. - `values` (object, optional): Values to override in the chart
  691. **Example:**
  692. ```json
  693. {
  694. "jsonrpc": "2.0",
  695. "id": 1,
  696. "method": "tools/call",
  697. "params": {
  698. "name": "helmInstall",
  699. "arguments": {
  700. "releaseName": "my-nginx",
  701. "chartName": "bitnami/nginx",
  702. "namespace": "web",
  703. "repoURL": "https://charts.bitnami.com/bitnami",
  704. "values": {
  705. "replicaCount": 3,
  706. "service": {
  707. "type": "LoadBalancer"
  708. }
  709. }
  710. }
  711. }
  712. }
  713. ```
  714. #### 15. `helmUpgrade`
  715. Upgrade an existing Helm release.
  716. **Parameters:**
  717. - `releaseName` (string, required): Name of the Helm release
  718. - `chartName` (string, required): Name or path of the Helm chart
  719. - `namespace` (string, required): Kubernetes namespace for the release (defaults to "default")
  720. - `repoURL` (string, optional): Helm repository URL; omit it for local chart paths or charts resolvable from configured repositories
  721. - `values` (object, required): Values to override in the chart
  722. **Example:**
  723. ```json
  724. {
  725. "jsonrpc": "2.0",
  726. "id": 1,
  727. "method": "tools/call",
  728. "params": {
  729. "name": "helmUpgrade",
  730. "arguments": {
  731. "releaseName": "my-nginx",
  732. "chartName": "nginx",
  733. "namespace": "web",
  734. "repoURL": "https://charts.bitnami.com/bitnami",
  735. "values": {
  736. "replicaCount": 2,
  737. "service": {
  738. "type": "NodePort"
  739. }
  740. }
  741. }
  742. }
  743. }
  744. ```
  745. #### 16. `helmList`
  746. List all Helm releases in the cluster or a specific namespace.
  747. #### 17. `helmGet`
  748. Get details of a specific Helm release.
  749. #### 18. `helmHistory`
  750. Get the history of a Helm release.
  751. #### 19. `helmRollback`
  752. Rollback a Helm release to a previous revision.
  753. #### 20. `helmUninstall`
  754. Uninstall a Helm release from the Kubernetes cluster.
  755. ### Adding New Tools
  756. 1. **Define the Tool**: In `tools/tools.go`, define a function that returns an `mcp.Tool` structure. This includes the tool's name, description, and input/output schemas.
  757. 2. **Implement the Handler**: In `handlers/handlers.go`, create a handler function. This function takes `*k8s.Client` as an argument and returns a function with the signature `func(context.Context, mcp.ToolInput) (mcp.ToolOutput, error)`. This inner function will contain the logic for your tool.
  758. 3. **Register the Tool**: In `main.go`, add your new tool to the MCP server instance using `s.AddTool(tools.YourToolDefinitionFunction(), handlers.YourToolHandlerFunction(client))`.
  759. ## Contributing
  760. Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to contribute to this project.
  761. ## License
  762. gholizade.net@gmail.com
  763. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
  764. <a href="https://glama.ai/mcp/servers/@reza-gholizade/k8s-mcp-server">
  765. <img width="380" height="200" src="https://glama.ai/mcp/servers/@reza-gholizade/k8s-mcp-server/badge" />
  766. </a>
  767. ## VS Code Integration
  768. ### Quick Setup
  769. #### Automatic Installation (Recommended)
  770. **macOS/Linux:**
  771. ```bash
  772. curl -sSL https://raw.githubusercontent.com/reza-gholizade/k8s-mcp-server/main/scripts/install-vscode-config.sh | bash
  773. ```
  774. **Windows (PowerShell):**
  775. ```powershell
  776. iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/reza-gholizade/k8s-mcp-server/main/scripts/install-vscode-config.ps1'))
  777. ```
  778. #### Manual Installation
  779. 1. **Install the MCP extension in VS Code:**
  780. ```bash
  781. code --install-extension modelcontextprotocol.mcp
  782. ```
  783. 2. **Add to your VS Code settings.json:**
  784. Open VS Code settings (Cmd/Ctrl + ,) → Open Settings JSON → Add:
  785. **macOS/Linux:**
  786. ```json
  787. {
  788. "mcp.mcpServers": {
  789. "k8s-mcp-server": {
  790. "command": "k8s-mcp-server",
  791. "args": ["--mode", "stdio"],
  792. "env": {
  793. "KUBECONFIG": "${env:HOME}/.kube/config"
  794. }
  795. }
  796. }
  797. }
  798. ```
  799. **Read-Only Mode (recommended for safety):**
  800. ```json
  801. {
  802. "mcp.mcpServers": {
  803. "k8s-mcp-server": {
  804. "command": "k8s-mcp-server",
  805. "args": ["--mode", "stdio", "--read-only"],
  806. "env": {
  807. "KUBECONFIG": "${env:HOME}/.kube/config"
  808. }
  809. }
  810. }
  811. }
  812. ```
  813. **Kubernetes Tools Only:**
  814. ```json
  815. {
  816. "mcp.mcpServers": {
  817. "k8s-mcp-server": {
  818. "command": "k8s-mcp-server",
  819. "args": ["--mode", "stdio", "--no-helm"],
  820. "env": {
  821. "KUBECONFIG": "${env:HOME}/.kube/config"
  822. }
  823. }
  824. }
  825. }
  826. ```
  827. **Helm Tools Only:**
  828. ```json
  829. {
  830. "mcp.mcpServers": {
  831. "k8s-mcp-server": {
  832. "command": "k8s-mcp-server",
  833. "args": ["--mode", "stdio", "--no-k8s"],
  834. "env": {
  835. "KUBECONFIG": "${env:HOME}/.kube/config"
  836. }
  837. }
  838. }
  839. }
  840. ```
  841. **Read-Only with Kubernetes Tools Only:**
  842. ```json
  843. {
  844. "mcp.mcpServers": {
  845. "k8s-mcp-server": {
  846. "command": "k8s-mcp-server",
  847. "args": ["--mode", "stdio", "--read-only", "--no-helm"],
  848. "env": {
  849. "KUBECONFIG": "${env:HOME}/.kube/config"
  850. }
  851. }
  852. }
  853. }
  854. ```
  855. **Windows:**
  856. ```json
  857. {
  858. "mcp.mcpServers": {
  859. "k8s-mcp-server": {
  860. "command": "k8s-mcp-server.exe",
  861. "args": ["--mode", "stdio"],
  862. "env": {
  863. "KUBECONFIG": "${env:USERPROFILE}/.kube/config"
  864. }
  865. }
  866. }
  867. }
  868. ```
  869. 3. **Ensure the binary is in your PATH:**
  870. Download the appropriate binary from the [releases page](https://github.com/reza-gholizade/k8s-mcp-server/releases) and add it to your system PATH.
  871. 4. **Restart VS Code**
  872. ### Usage in VS Code
  873. Once configured, you can use the Kubernetes MCP server in VS Code with Claude or other MCP-compatible tools:
  874. 1. Open VS Code
  875. 2. Access Claude (or other MCP-enabled AI assistant)
  876. 3. Use natural language to interact with your Kubernetes cluster:
  877. - "List all pods in the default namespace"
  878. - "Show me the logs for pod nginx-123"
  879. - "Get the CPU usage for worker-node-1"
  880. - "Describe the deployment called my-app"
  881. ### Configuration Options
  882. You can customize the configuration by modifying the settings:
  883. ```json
  884. {
  885. "mcp.mcpServers": {
  886. "k8s-mcp-server": {
  887. "command": "k8s-mcp-server",
  888. "args": ["--mode", "stdio"],
  889. "env": {
  890. "KUBECONFIG": "/path/to/your/kubeconfig",
  891. "KUBERNETES_CONTEXT": "your-context-name"
  892. }
  893. }
  894. }
  895. }
  896. ```
  897. ### Troubleshooting
  898. - **Binary not found**: Ensure `k8s-mcp-server` is in your PATH
  899. - **Kubernetes connection issues**: Verify your `KUBECONFIG` path is correct
  900. - **Permission errors**: Ensure your kubeconfig has the necessary RBAC permissions
  901. - **Extension not loading**: Restart VS Code after configuration changes

Ratings and comments

Sign in to rate this skill.

Sign in

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