{"id":17772,"library":"kubernetes-mcp-server","title":"Kubernetes MCP Server","description":"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.","status":"active","version":"0.0.60","language":"javascript","source_language":"en","source_url":"https://github.com/containers/kubernetes-mcp-server","tags":["javascript","mcp","kubernetes","openshift","model context protocol","model","context","protocol"],"install":[{"cmd":"npm install kubernetes-mcp-server","lang":"bash","label":"npm"},{"cmd":"yarn add kubernetes-mcp-server","lang":"bash","label":"yarn"},{"cmd":"pnpm add kubernetes-mcp-server","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[],"quickstart":{"code":"const { spawn } = require('child_process');\n\nconsole.log('Starting Kubernetes MCP Server via npx...');\nconsole.log('It will use your default KUBECONFIG or the one specified by the KUBECONFIG environment variable.');\n\nconst serverProcess = spawn('npx', [\n  'kubernetes-mcp-server',\n  '--port', '8080', // Default port, can be customized\n  '--log-level', 'info', // Adjust log verbosity\n  '--disable-multi-cluster' // Optional: use if default multi-cluster behavior (v0.0.53+) is undesired\n], {\n  stdio: 'inherit', // Stream output (logs, errors) to the parent process\n  env: { ...process.env, KUBECONFIG: process.env.KUBECONFIG ?? '~/.kube/config' } // Ensure KUBECONFIG is set or defaults\n});\n\nserverProcess.on('error', (err) => {\n  console.error('Failed to start kubernetes-mcp-server:', err);\n});\n\nserverProcess.on('exit', (code) => {\n  if (code !== 0) {\n    console.error(`Kubernetes MCP Server exited with code ${code}`);\n  } else {\n    console.log('Kubernetes MCP Server exited successfully.');\n  }\n});\n\nconsole.log('Kubernetes MCP Server running on port 8080. You can now access its API, e.g., by running:');\nconsole.log('  curl http://localhost:8080/stats');\nconsole.log('  curl http://localhost:8080/api/v1/namespaces');\n// In a real application, you would manage this process with a daemon or process manager\n// and interact with its HTTP API programmatically.","lang":"javascript","description":"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."},"warnings":[{"fix":"Update your custom code calling `provider.GetTargets` to accommodate the new signature, which now accepts an optional user-scoping parameter.","message":"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.","severity":"breaking","affected_versions":">=0.0.60"},{"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.","message":"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.","severity":"breaking","affected_versions":">=0.0.53"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"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.","cause":"The `kubernetes-mcp-server` executable is not in your system's PATH, or the npm package wrapper is not installed or available locally.","error":"command not found: kubernetes-mcp-server"},{"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`).","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.","error":"Error: dial tcp 127.0.0.1:8080: connect: connection refused"},{"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.","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).","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"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}