Registry / devops / mcp-server-kubernetes

mcp-server-kubernetes

JSON →
library0.1.6jsnpmunverified

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.

devopshttp-networkingobservability
npm install mcp-server-kubernetes
github ↗package ↗homepage ↗
INSTALL
IMPORT
SIG · MCP-SERVER-KUBERNE
M
mcp-server-kubernetes
devopsjavascriptv0.1.6
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Direct Server Execution
✓ npx mcp-server-kubernetes --port 8080
✗ import { startServer } from 'mcp-server-kubernetes'
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
✓ Install via Claude Desktop's Extensions browser or manually download the `.mcpb` file from GitHub releases.
✗ npm install mcp-server-kubernetes and expecting automatic integration with Claude Desktop.
For Claude Desktop, the server is primarily distributed and installed as a `.mcpb` extension, streamlining setup within the IDE.

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!
kubernetes --version
Debug
Known issues
gotchaThe 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`).
affects: >=3.0.0
gotchaOlder 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.
affects: <3.4.0
gotchaVersion 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.
affects: >=3.2.0
gotchaThis 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.
affects: >=3.0.0
Errors
Common errors & fixes
Error: Command failed: kubectl get pods -o json (or similar kubectl command) /bin/sh: kubectl: command not found
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
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
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.
Upgrade
Version history
0.1.6latest on npm
Audit
Dependencies
kubectlrequiredRequired CLI tool for interacting with Kubernetes clusters, which this server wraps. Must be installed and in the system PATH.
helmoptionalRequired CLI tool for managing Helm charts via this server's capabilities. Only needed if Helm chart operations are performed.
Agent activity
10 hits · last 30 days
node
8
OpenAI (training)
2
Resources
githubhttps://github.com/Flux159/mcp-server-kubernetes ↗
packagehttps://www.npmjs.com/package/mcp-server-kubernetes ↗
homepagehttps://mcp-kubernetes.com ↗