MCP Server Kubernetes

3.5.0 · active · verified Sun Apr 19

The `mcp-server-kubernetes` package provides an executable Model Context Protocol (MCP) server designed to facilitate interaction with Kubernetes clusters. It leverages the local `kubectl` installation and `kubeconfig` files to perform operations such as managing pods, deployments, and other Kubernetes resources. The current stable version is 3.5.0, with the project demonstrating an active development cadence through frequent minor and patch releases, as seen with recent updates like 3.4.0 and 3.3.0. A key differentiator is its deep integration into the Claude ecosystem, offering streamlined setup for Claude Code and Claude Desktop through dedicated commands and `.mcpb` extensions. It supports various `kubeconfig` loading strategies, provides an `X-MCP-AUTH` header for basic authentication in streaming server contexts, and includes advanced features like OpenTelemetry distributed tracing support since v3.3.0. This server acts as a crucial bridge for AI agents and developer tools that need programmatic access to Kubernetes management capabilities via the MCP standard, abstracting the complexities of direct `kubectl` interaction.

Common errors

```
Error: Command failed: kubectl get pods -o json (or similar kubectl command) /bin/sh: kubectl: command not found
```
cause The `kubectl` command-line tool is not installed or not present in the system's PATH environment variable.

fix Install `kubectl` according to official Kubernetes documentation for your operating system and ensure its executable path is included in your system's PATH.
```
Error: Failed to connect to Kubernetes cluster: No valid kubeconfig contexts found
```
cause The server cannot find or access a valid `kubeconfig` file with configured contexts to connect to a Kubernetes cluster.

fix Ensure you have a valid `kubeconfig` file (default: `~/.kube/config`) and that it contains at least one accessible context. Verify connection with `kubectl get pods` manually. For advanced options, refer to `ADVANCED_README.md` for custom paths or environment variables.
```
HTTP 401 Unauthorized: X-MCP-AUTH header is missing or invalid
```
cause The server has been configured with `X-MCP-AUTH` authentication, but the client request is missing the required `X-MCP-AUTH` header or provides an incorrect token.

fix Ensure the client includes an `X-MCP-AUTH` header with the correct token that matches the `X_MCP_AUTH_TOKEN` environment variable set on the server.

Warnings

gotcha The server relies on `kubectl` and `helm` (if used) being installed and accessible in the system's PATH. Ensure a valid `kubeconfig` file with configured contexts is also available.
Fix: Verify `kubectl` and `helm` installations with `kubectl version` and `helm version`. Ensure `~/.kube/config` is correctly configured or provide a custom path via environment variables (see `ADVANCED_README.md`).
gotcha Older versions (prior to v3.4.0) could experience stale Kubernetes reconnections, potentially leading to unresponsive operations over long periods.
Fix: Upgrade to v3.4.0 or newer to benefit from the `kubectl_reconnect` command and associated bug fixes that address stale connections.
gotcha Version 3.2.0 introduced `X-MCP-AUTH` as a simple authentication mechanism. If you require authentication, you must explicitly configure `X_MCP_AUTH_TOKEN` environment variable; otherwise, the server will operate unauthenticated.
Fix: Set the `X_MCP_AUTH_TOKEN` environment variable with your desired token before starting the server. Clients must then include `X-MCP-AUTH: <your_token>` in their requests.
gotcha This package is an executable server and not intended for programmatic `import` or `require` as a library. Attempting to use it as a module will lead to runtime errors.
Fix: Interact with the server by running its command-line executable (`npx mcp-server-kubernetes`) or through an MCP client that manages its process.

Install

npm install mcp-server-kubernetes npm
yarn add mcp-server-kubernetes yarn
pnpm add mcp-server-kubernetes pnpm

Imports

Direct Server Execution
wrong:
```
import { startServer } from 'mcp-server-kubernetes'
```
correct:
```
npx mcp-server-kubernetes --port 8080
```
This package is a CLI executable, not a library. It is run directly using `npx` or by installing globally and invoking `mcp-server-kubernetes`.
Claude Code Integration
```
claude mcp add kubernetes -- npx mcp-server-kubernetes
```
This is the recommended method for integrating the server within the Claude Code environment, abstracting direct command line invocation.

Claude Desktop Extension

wrong:

npm install mcp-server-kubernetes and expecting automatic integration with Claude Desktop.

correct:

Install via Claude Desktop's Extensions browser or manually download the `.mcpb` file from GitHub releases.

For Claude Desktop, the server is primarily distributed and installed as a `.mcpb` extension, streamlining setup within the IDE.

Quickstart

Demonstrates how to install the MCP Kubernetes server globally, run it directly, and integrate it with Claude Code for local development.

// This quickstart demonstrates how to install and run the mcp-server-kubernetes
// as a standalone process and how to integrate it with Claude Code.
// Ensure you have Node.js (>=18) and npm installed.
// Also, `kubectl` and a valid `kubeconfig` must be present and configured.

// Step 1: Install the server globally for easy execution.
// This is typically how you'd make it available for npx or direct command.
// If you prefer local installation, omit `-g` and use `npx mcp-server-kubernetes`.
// In your terminal, run:
// npm install -g mcp-server-kubernetes

// Step 2: Run the server directly (e.g., for testing or custom integrations).
// The server will listen on the specified port, interacting with your Kubernetes cluster.
// For security, consider setting authentication via X-MCP-AUTH environment variables.
// In your terminal, run:
// npx mcp-server-kubernetes --port 8080 --log-level info
// Example with authentication (replace 'mysecrettoken'):
// X_MCP_AUTH_TOKEN="mysecrettoken" npx mcp-server-kubernetes --port 8080

// Step 3: Integrate with Claude Code (if applicable).
// This command registers the server with your Claude Code environment.
// In your terminal, run:
// claude mcp add kubernetes -- npx mcp-server-kubernetes

// The server is now ready to interact with Kubernetes via MCP!

view raw JSON →