home / mcp / k8s mcp server

K8s MCP Server

Provides dynamic multi-cluster MCP access to Kubernetes tools like kubectl, helm, istioctl, and argocd via HTTP endpoints.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "apecloud-mcp-k8s": {
      "url": "http://localhost:9096/mcp"
    }
  }
}

You can run a Kubernetes MCP server that exposes standard MCP endpoints for popular Kubernetes CLI tools. It lets you dynamically pass kubeconfig data per request so you can manage multiple clusters safely from an LLM or other MCP clients. The server automatically documents its API and provides dedicated endpoints for each tool like kubectl, helm, istioctl, and argocd.

How to use

Connect your MCP client to the server to discover available tools and issue commands. Each tool has its own HTTP endpoint, and you supply a kubeconfig either as a request header or as part of the request body. The server runs the execution engine which creates a temporary kubeconfig, runs the requested command, and returns the results back through the MCP channel.

How to install

Prerequisites: you need Docker or Python to run the server locally. You also require internet access to pull images or install dependencies.

# Quick start with Docker (local development)
docker run -d --rm -p 9096:9096 --name mcp-server \
  docker.io/apecloud/k8s-mcp-server:latest

# Alternatively, run from source (see next section for details)

Additional configuration and operation notes

HTTP MCP configuration (remote server) allows your MCP client to target a specific MCP endpoint directly. If you already have a running server, you can configure your client as follows.

{
  "mcpServers": {
    "kubernetes": {
      "url": "http://localhost:9096/mcp"
    }
  }
}

Local development and run from source

If you prefer to run the server directly from the source, follow these steps.

# 1. Clone the repository
git clone https://github.com/apecloud/mcp-k8s.git
cd mcp-k8s

# 2. Create and activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate

# 3. Install dependencies
pip install .

# 4. Run the server with UVicorn
uvicorn src.k8s_mcp_server.app:app --host 0.0.0.0 --port 9096

Security and usage notes

The server executes commands in a non-root context inside containers to improve security. You can pass kubeconfig data per request, which enables safe multi-cluster management without pre-mounting cluster credentials.

API and tool endpoints

The server exposes independent endpoints for each Kubernetes tool. Examples of supported tools include kubectl, helm, istioctl, and argocd. These endpoints are discoverable by MCP clients and come with OpenAPI documentation automatically generated by FastAPI.

Validation and health

After starting, verify the server is healthy by checking the health endpoint. The server exposes a /health route that returns a healthy status when it is ready.

Available tools

kubectl

Executes Kubernetes cluster operations such as listing pods, deployments, and resources using the kubectl CLI through the MCP endpoint.

helm

Manages Kubernetes charts and releases via the Helm CLI through the MCP endpoint.

istioctl

Interacts with Istio service mesh configurations and workloads using istioctl through the MCP endpoint.

argocd

Automates Argo CD operations and deployments via the argocd CLI through the MCP endpoint.