{"id":11276,"library":"mcp-server-kubernetes","title":"MCP Server Kubernetes","description":"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.","status":"active","version":"3.5.0","language":"javascript","source_language":"en","source_url":"https://github.com/Flux159/mcp-server-kubernetes","tags":["javascript","mcp","kubernetes","claude","anthropic","kubectl"],"install":[{"cmd":"npm install mcp-server-kubernetes","lang":"bash","label":"npm"},{"cmd":"yarn add mcp-server-kubernetes","lang":"bash","label":"yarn"},{"cmd":"pnpm add mcp-server-kubernetes","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required CLI tool for interacting with Kubernetes clusters, which this server wraps. Must be installed and in the system PATH.","package":"kubectl","optional":false},{"reason":"Required CLI tool for managing Helm charts via this server's capabilities. Only needed if Helm chart operations are performed.","package":"helm","optional":true}],"imports":[{"note":"This package is a CLI executable, not a library. It is run directly using `npx` or by installing globally and invoking `mcp-server-kubernetes`.","wrong":"import { startServer } from 'mcp-server-kubernetes'","symbol":"Direct Server Execution","correct":"npx mcp-server-kubernetes --port 8080"},{"note":"This is the recommended method for integrating the server within the Claude Code environment, abstracting direct command line invocation.","symbol":"Claude Code Integration","correct":"claude mcp add kubernetes -- npx mcp-server-kubernetes"},{"note":"For Claude Desktop, the server is primarily distributed and installed as a `.mcpb` extension, streamlining setup within the IDE.","wrong":"npm install mcp-server-kubernetes and expecting automatic integration with Claude Desktop.","symbol":"Claude Desktop Extension","correct":"Install via Claude Desktop's Extensions browser or manually download the `.mcpb` file from GitHub releases."}],"quickstart":{"code":"// This quickstart demonstrates how to install and run the mcp-server-kubernetes\n// as a standalone process and how to integrate it with Claude Code.\n// Ensure you have Node.js (>=18) and npm installed.\n// Also, `kubectl` and a valid `kubeconfig` must be present and configured.\n\n// Step 1: Install the server globally for easy execution.\n// This is typically how you'd make it available for npx or direct command.\n// If you prefer local installation, omit `-g` and use `npx mcp-server-kubernetes`.\n// In your terminal, run:\n// npm install -g mcp-server-kubernetes\n\n// Step 2: Run the server directly (e.g., for testing or custom integrations).\n// The server will listen on the specified port, interacting with your Kubernetes cluster.\n// For security, consider setting authentication via X-MCP-AUTH environment variables.\n// In your terminal, run:\n// npx mcp-server-kubernetes --port 8080 --log-level info\n// Example with authentication (replace 'mysecrettoken'):\n// X_MCP_AUTH_TOKEN=\"mysecrettoken\" npx mcp-server-kubernetes --port 8080\n\n// Step 3: Integrate with Claude Code (if applicable).\n// This command registers the server with your Claude Code environment.\n// In your terminal, run:\n// claude mcp add kubernetes -- npx mcp-server-kubernetes\n\n// The server is now ready to interact with Kubernetes via MCP!","lang":"javascript","description":"Demonstrates how to install the MCP Kubernetes server globally, run it directly, and integrate it with Claude Code for local development."},"warnings":[{"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`).","message":"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.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Upgrade to v3.4.0 or newer to benefit from the `kubectl_reconnect` command and associated bug fixes that address stale connections.","message":"Older versions (prior to v3.4.0) could experience stale Kubernetes reconnections, potentially leading to unresponsive operations over long periods.","severity":"gotcha","affected_versions":"<3.4.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=3.2.0"},{"fix":"Interact with the server by running its command-line executable (`npx mcp-server-kubernetes`) or through an MCP client that manages its process.","message":"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.","severity":"gotcha","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Install `kubectl` according to official Kubernetes documentation for your operating system and ensure its executable path is included in your system's PATH.","cause":"The `kubectl` command-line tool is not installed or not present in the system's PATH environment variable.","error":"Error: Command failed: kubectl get pods -o json (or similar kubectl command) /bin/sh: kubectl: command not found"},{"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.","cause":"The server cannot find or access a valid `kubeconfig` file with configured contexts to connect to a Kubernetes cluster.","error":"Error: Failed to connect to Kubernetes cluster: No valid kubeconfig contexts found"},{"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.","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.","error":"HTTP 401 Unauthorized: X-MCP-AUTH header is missing or invalid"}],"ecosystem":"npm"}