K8s Cluster Ops MCP Server

A Kubernetes operations query MCP service based on FastMCP. It wraps daily troubleshooting actions such as kubectl get / describe / logs / events --watch into read-only tools callable by LLMs, allowing clients like Claude to directly read cluster status and locate the source of problems.

⚠️ This project only exposes read-only tools (no create/update/delete). However, it is still recommended to use it with RBAC for a read-only ServiceAccount, see 'Security Recommendations' below.

Tool List

There are also two additional capabilities: @mcp.prompt (node troubleshooting / cluster inspection guidance) and @mcp.resource (k8s://cluster/summary cluster summary).

Related MCP server: k8s-readonly-mcp

Directory Structure

├── app.py              # FastMCP 实例（叶子模块，破循环导入）
├── k8s_server.py       # 入口：导入 Tools 即自动注册全部工具
├── k8s_client.py       # K8s 客户端懒加载 + 单一配置真源
├── config.py           # 12-Factor 环境变量配置
├── prompts.py          # @mcp.prompt 引导
├── resources.py        # @mcp.resource 资源
├── Tools/              # 每个工具一个文件，导入即注册
├── utils/              # 纯解析/辅助模块（无 K8s/MCP 依赖）
└── tests/              # 单元测试

Installation and Running

# 1. 创建虚拟环境并安装依赖
python -m venv .venv
# Windows
.venv\Scripts\activate
# Linux / macOS
source .venv/bin/activate

pip install -r requirements.txt

# 2. 运行（HTTP transport，默认 127.0.0.1:8081）
python k8s_server.py

Run Tests

pip install -r requirements-dev.txt
python -m pytest -q

Configuration

All configuration is done through environment variables with defaults (see config.py):

K8s connection configuration loading priority: in-cluster (SA inside Pod) → explicit KUBECONFIG_PATH → official kubeconfig resolution chain, a single source of truth, not assembled from multiple files.

Connect to MCP Client

Using Claude Code as an example (when the HTTP transport is already running on 127.0.0.1:8081):

{
  "mcpServers": {
    "k8s-node-server": {
      "url": "http://127.0.0.1:8081/mcp"
    }
  }
}

Security Recommendations

1. Use read-only RBAC: configure a read-only ClusterRole for the Pods/users running this service, and avoid reusing high-privilege credentials.

2. Bind to localhost by default: MCP_HOST defaults to 127.0.0.1. If you need to expose it externally, be sure to add authentication (TLS + Token / OIDC) at the reverse proxy layer, because the HTTP transport itself has no authentication or rate limiting.

3. Do not disable certificate verification: K8S_VERIFY_SSL=false is only for temporarily debugging self-signed certificates; keep it true in production.

4. Do not commit credentials: kubeconfig contains secrets; .gitignore already excludes kubeconfig*, never force-commit it.

Known Limitations

• All tools are read-only and contain no mutation operations (this is by design).

• The watch_* family is limited by a global concurrency lock: only one watch is allowed to run at a time, to avoid adding pressure to the API Server.

• Event/log output has a length limit; oversized content will be truncated (see the truncation logic in read_pod_log and max_count in query_events).