mcp -kubernetes

This MCP server provides a unified interface for managing resources in a Kubernetes cluster. It exposes a set of MCP tools that wrap kubectl functionality, offering commands like kubectl_get, kubectl_apply, kubectl_create, kubectl_delete, kubectl_describe, kubectl_logs, and kubectl_context, as well as higher-level operations such as kubectl_rollout, kubectl_patch, kubectl_scale, and kubectl_generic. There is also support for Helm operations (install, upgrade, uninstall) and template-based flows (helm_template_apply/helm_template_uninstall) to help bypass certain authentication pitfalls. Advanced capabilities include port forwarding, node management (cordon/drain/uncordon), and a non-destructive mode for read and limited write access. OpenTelemetry observability can be enabled for distributed tracing across tool calls.

To use the server, connect via your preferred MCP client (Claude Code/Claude Desktop, mcp-chat CLI, VS Code, Cursor, Gemini CLI, or native MCP-enabled integrations). For Claude Code, add the MCP server using the built-in command so Claude can route queries to kubectl-backed operations. For editors like VS Code and Cursor, configure the mcpServers section to point at the npx mcp-server-kubernetes entry, which will manage your Kubernetes context and resources through the MCP layer. You can also run the server locally with npx mcp-server-kubernetes and then point your MCP client at that instance.

Once connected, you can issue commands such as kubectl_get pods --all-namespaces, kubectl_apply -f deployment.yaml, or kubectl_logs my-pod -c my-container, all through the MCP interface. The server uses your kubeconfig context by default, and it can load kubeconfig from multiple sources in a priority order, with the default path at ~/.kube/config, while supporting environment-based or custom path configurations if you supply the appropriate environment settings.

Prerequisites:

• A Kubernetes setup with kubectl configured (kubectl in PATH) and a kubeconfig available.
• Node.js and npm (or Bun) installed, or Bun installed for Bun runtime usage as indicated by the project badges.
• Helm v3 installed if you plan to use Helm operations.

Installation steps:

1. Install a JavaScript/Node.js runtime (recommended: Node.js 18+ with npm):

   • Install Node.js from https://nodejs.org/ (npm comes bundled with Node.js)

2. Alternatively, install Bun (optional, if you prefer Bun):

   • Install Bun: https://bun.sh/

3. Install and run the MCP server via npx:

   • Ensure your environment has access to the npm registry.

   • Run the MCP server:

     npx mcp-server-kubernetes

4. (Optional) Use Docker for containerized usage (if you prefer):

   • Build/run instructions will be provided in the repository; generally you can use a Kubernetes-compatible container and ensure kubectl inside the container has access to kubeconfig.

5. Confirm connectivity:

   • From a terminal, verify that kubectl can reach your cluster (kubectl get pods).
   • Connect an MCP client (Claude Code, Claude Desktop, VS Code, Cursor, or mcp-chat) to the running mcp-server-kubernetes instance using the configuration shown in the README (npx mcp-server-kubernetes as the server command).

6. Optional environment configuration:

   • You can override kubeconfig locations or add credentials via environment variables as described in ADVANCED_README.md (e.g., KUBECONFIG, KUBE_CONFIG_PATH).

Tips and common issues:

• By default, the MCP Kubernetes server loads kubeconfig from ~/.kube/config. If you have multiple sources (environment variables, custom paths), ensure they’re defined in your environment or provided to the MCP client configuration.
• When using Helm operations, ensure Helm v3 is installed and accessible in PATH. Helm templates can help bypass authentication issues when installing charts.
• Secrets in kubectl get secrets are masked by the server for security, but logs may still contain sensitive values depending on your command outputs; review logging configurations if necessary.
• Enable OpenTelemetry observability if you need distributed tracing for tool calls. This can help diagnose performance issues and errors across kubectl, Helm, and related operations.
• If using VS Code, Claude Desktop, or Cursor, ensure their MCP configuration JSON includes the server as shown and that the description field (where present) clarifies the server’s purpose (Kubernetes cluster management).
• The server supports a non-destructive mode for read-only or limited update access; use kubectl_get or read-only operations to minimize impact during investigations.
• For mcp-chat usage, you can connect by running: npx mcp-chat --server "npx mcp-server-kubernetes" to start interacting with Kubernetes via MCP.