mcp-kubernetes-ro

mcp-kubernetes-ro provides a read-only MCP server interface that lets AI assistants inspect Kubernetes clusters without performing destructive operations. It leverages your kubeconfig to connect to clusters and exposes tools for listing resources, fetching resource details, retrieving pod logs, discovering API resources, and performing base64 encode/decode operations. It supports multiple transport modes (stdio and SSE) and can be run via npx, a binary, or a Docker image, giving you flexible deployment options. The server enforces read-only access to protect clusters while still offering comprehensive visibility and troubleshooting capability.

To use it, install or run the server via the provided npm package, a prebuilt binary, or a Docker image, then configure the MCP client (such as an AI agent) to point at the server and use the available tools. The available MCP tools include listing resources by type, getting detailed resource data, viewing pod logs with filtering, listing API resources, and encoding/decoding base64 data. You can also limit tools per deployment by using the --disabled-tools flag or the corresponding environment variables. Ensure your kubeconfig is accessible to the server (either by mounting or by using the KUBECONFIG path) so that the server can connect to your clusters and perform read-only queries safely.

Prerequisites:\n- A Kubernetes cluster with a valid kubeconfig file (typically ~/.kube/config)\n- Access credentials with read permissions; destructive operations are disabled by design.\n- Optional: Metrics Server installed in your cluster if you plan to use get_node_metrics or get_pod_metrics. If not present, those tools will return an error.\n\n1) Prerequisites install (Node.js and npm must be available for npx): ensure you have Node and npm installed. You can skip if you prefer the binary or Docker route.\n\n2) Run with npx (recommended for quick start):\nbash\nnpx -y @patrickdappollonio/mcp-kubernetes-ro\n\nThis will fetch the package and run the MCP server with default settings. You can override kubeconfig, namespace, transport, port, and disabled tools via CLI flags or environment variables (see below).\n\n3) Install as a binary (prebuilt)\n- Download the prebuilt binary from the releases page and place it on your PATH.\n- Run the binary directly: mcp-kubernetes-ro (or the exact binary name).\n\n4) Docker usage\n- Pull and run the Docker image:\nbash\ndocker pull ghcr.io/patrickdappollonio/mcp-kubernetes-ro:latest\ndocker run -it --rm -v ~/.kube:/root/.kube -v ~/.kube/config:/root/.kube/config ghcr.io/patrickdappollonio/mcp-kubernetes-ro:latest\n\n- Ensure the kubeconfig path is mounted or provided to the container, or set KUBECONFIG accordingly inside the container.\n\n5) Editor configuration (example)\n- You can embed the server configuration in your editor or agent settings as shown in the README. Use the provided JSON-like structure to point your agent at the MCP server.\n\n6) Environment variables and flags (examples)\n- KUBECONFIG: path to kubeconfig if not using default mount.\n- DISABLED_TOOLS: comma-separated list to disable specific tools (e.g., get_logs, decode_base64).\n- MCP_KUBERNETES_RO_DISABLED_TOOLS: explicit per-tool suppression.\n- --disabled-tools flag can be used on the command line if supported by your launcher.\n\nNote: The server emphasizes read-only access. Ensure you do not expose destructive commands and that your kubeconfig permissions align with read-only operations.\n

Tips and common issues:\n- If get_node_metrics or get_pod_metrics fail, ensure Metrics Server is installed in your cluster. These tools depend on metrics endpoints.\n- To limit capabilities, use --disabled-tools or the corresponding environment variables (MCP_KUBERNETES_RO_DISABLED_TOOLS or DISABLED_TOOLS).\n- When using Docker, mount your kubeconfig into the container and point the server at it (either via KUBECONFIG or the --kubeconfig flag).\n- The server can operate without the kubectl binary present on the host; it uses the kubeconfig to access the cluster.\n- You can specify namespaces per command or operate cluster-wide; use the appropriate flags for per-command contexts.\n- If you encounter connectivity issues on startup, verify that the kubeconfig context is valid and that the server has network access to the cluster API server.