kubernetes

This MCP server exposes the Kubernetes resources through the MCP (Model Context Protocol) interface, allowing clients to synchronize cluster state using a stable API surface. Once running, clients can connect to the MCP endpoint exposed by the Docker container and begin watching for resource changes (such as Pods, Deployments, Services, and Custom Resources) in the specified Kubernetes namespace. The server translates Kubernetes API state into MCP models so that clients can receive incremental updates and perform read operations efficiently. Typical workflows include initial full-sync, streaming updates, and on-demand queries for resource metadata and status. The server is designed to operate in cluster or out-of-cluster environments and aims to minimize the latency between Kubernetes events and MCP clients.

Prerequisites:

• Docker installed and running on the host
• Access to the Kubernetes cluster you want to observe

Step-by-step:

1. Pull and run the MCP Kubernetes server container: docker run -i blankcut/kubernetes-mcp-server

2. If you need to target a specific namespace, set the NAMESPACE environment variable when running the container: docker run -e NAMESPACE=default -i blankcut/kubernetes-mcp-server

3. (Optional) Configure logging verbosity via MCP_LOG_LEVEL (e.g., debug, info, warn, error): docker run -e MCP_LOG_LEVEL=debug -i blankcut/kubernetes-mcp-server

4. Ensure network access from your MCP clients to the container’s MCP endpoint. The server will expose the MCP API surface for subscription and query operations. Refer to client documentation for the exact MCP methods supported by this server.

Tips and common issues:

• Ensure the Kubernetes cluster you intend to observe is accessible from the host running Docker.
• If running in a restricted environment, you may need to pass additional environment variables or mount service account credentials depending on your cluster configuration.
• The NAMESPACE env var controls which namespace is monitored; leaving it empty may monitor all namespaces depending on the container’s implementation.
• If you experience connection errors, verify that the container is running and that firewall rules allow traffic to the MCP port used by clients.
• This MCP server focuses on translating Kubernetes state to MCP models; it may not cover every Kubernetes resource out of the box. Check for supported resource types and any required CRD installations in your cluster.
• For production deployments, consider using a Kubernetes-native deployment approach or a more robust orchestration mechanism to manage the lifecycle of the MCP server container.