Registry / devops / kubernetes-mcp-server

kubernetes-mcp-server

JSON →
library0.0.60jsnpmunverified

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.

npm install kubernetes-mcp-server
INSTALL
IMPORT
SIG · KUBERNETES-MCP-SER
K
kubernetes-mcp-server
devopsjavascriptv0.0.60
harness data pending
Install & Compatibility
Where this runs

No compatibility data collected yet for this library.

Code
Verified usage

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.
Debug
Known issues
breakingThe `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.
affects: >=0.0.60
breakingStarting 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.
affects: >=0.0.53
gotchaThe `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.
affects: All
Errors
Common errors & fixes
command not found: kubernetes-mcp-server
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: dial tcp 127.0.0.1:8080: connect: connection refused
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`).
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
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.
Upgrade
Version history
0.0.60latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
23 hits · last 30 days
node
20
OpenAI (training)
1
Resources
kubernetes-mcp-server — npm install kubernetes-mcp-server · libregistry