Kubernetes MCP Server

0.0.60 verified Thu Apr 23 auth: no javascript

The Kubernetes Model Context Protocol (MCP) Server provides a native Go-based implementation for interacting with Kubernetes and OpenShift clusters. Unlike many alternatives, it avoids wrapping `kubectl` or `helm` command-line tools, opting for direct interaction with the Kubernetes API server to deliver high performance and low latency. The current stable version is `0.0.60`. Release cadence is frequent, indicating active development. Key features include automatic configuration updates, comprehensive CRUD operations on generic Kubernetes resources, Pod-specific operations (logs, exec, top), Namespace and Event management, OpenShift Project listing, and full Helm chart management (install, list, uninstall). It supports multi-cluster environments via `kubeconfig` and integrates optional OpenTelemetry distributed tracing and metrics. The server is distributed as a single native binary for various operating systems (Linux, macOS, Windows), an npm package (which is a wrapper for the binary), a Python package, and a Docker image, requiring no external dependencies like Node.js or Python on the host system when using the native binary.

Common errors

error command not found: kubernetes-mcp-server ↓

cause The `kubernetes-mcp-server` executable is not in your system's PATH, or the npm package wrapper is not installed or available locally.

fix

Install the package globally using npm install -g kubernetes-mcp-server, or execute it directly with npx kubernetes-mcp-server to leverage the local node_modules executable.

error Error: dial tcp 127.0.0.1:8080: connect: connection refused ↓

cause The Kubernetes MCP Server is not running, or it is listening on a different IP address or port than the one you are trying to connect to.

fix

Ensure the server process is actively running. Check its startup logs for the actual listening address and port, or explicitly specify them using the --port and --bind-address flags when launching the server (e.g., npx kubernetes-mcp-server --port 8081).

error E0423 15:30:00.123456 1 reflector.go:140] k8s.io/client-go/informers/factory.go:134: Failed to list *v1.Pod: pods is forbidden: User "system:anonymous" cannot list resource "pods" in API group "" at the cluster scope ↓

cause The `kubeconfig` used by the Kubernetes MCP Server does not have sufficient Role-Based Access Control (RBAC) permissions to access the Kubernetes cluster or specific resources (like listing pods).

fix

Provide a kubeconfig file with the necessary RBAC permissions for the server to operate. Verify your KUBECONFIG environment variable is correctly set, or ensure the server is running within a Kubernetes cluster with a service account that has been granted appropriate roles.

Warnings

breaking The `provider.GetTargets` method signature has changed to optionally accept user-scoping. If you have custom code that calls this method, you will need to update the call sites to match the new signature. ↓

fix Update your custom code calling `provider.GetTargets` to accommodate the new signature, which now accepts an optional user-scoping parameter.

breaking Starting with v0.0.53, multi-cluster support is enabled by default. If your `kubeconfig` contains multiple context definitions, these will be made available as an extra `context` parameter for tools. This behavioral change may affect existing setups expecting single-cluster interactions. ↓

fix If this new multi-cluster behavior breaks your current setup, disable the feature by providing the `--disable-multi-cluster` CLI flag when starting the server, or by setting a specific `cluster_provider_strategy` in your Kubernetes MCP server's TOML configuration.

gotcha The `kubernetes-mcp-server` npm package is a wrapper for a Go-based native binary, not a traditional JavaScript library. It primarily provides a command-line interface to start and manage the server. ↓

fix Understand that interaction with the server is typically via CLI commands (e.g., `npx kubernetes-mcp-server`) to start it, and then by making HTTP requests to the running server's API endpoints, rather than importing JavaScript modules and calling functions directly.

Install

npm install kubernetes-mcp-server

yarn add kubernetes-mcp-server

pnpm add kubernetes-mcp-server

Quickstart

This quickstart demonstrates how to launch the Kubernetes MCP Server as a background process using `npx`, configuring its port and a specific flag, and hinting at API interaction.

const { spawn } = require('child_process');

console.log('Starting Kubernetes MCP Server via npx...');
console.log('It will use your default KUBECONFIG or the one specified by the KUBECONFIG environment variable.');

const serverProcess = spawn('npx', [
  'kubernetes-mcp-server',
  '--port', '8080', // Default port, can be customized
  '--log-level', 'info', // Adjust log verbosity
  '--disable-multi-cluster' // Optional: use if default multi-cluster behavior (v0.0.53+) is undesired
], {
  stdio: 'inherit', // Stream output (logs, errors) to the parent process
  env: { ...process.env, KUBECONFIG: process.env.KUBECONFIG ?? '~/.kube/config' } // Ensure KUBECONFIG is set or defaults
});

serverProcess.on('error', (err) => {
  console.error('Failed to start kubernetes-mcp-server:', err);
});

serverProcess.on('exit', (code) => {
  if (code !== 0) {
    console.error(`Kubernetes MCP Server exited with code ${code}`);
  } else {
    console.log('Kubernetes MCP Server exited successfully.');
  }
});

console.log('Kubernetes MCP Server running on port 8080. You can now access its API, e.g., by running:');
console.log('  curl http://localhost:8080/stats');
console.log('  curl http://localhost:8080/api/v1/namespaces');
// In a real application, you would manage this process with a daemon or process manager
// and interact with its HTTP API programmatically.