kubernetools MCP Server

kubernetools/mcp-server

用于 kubernetools MCP 服务器的容器镜像。

仓库： ghcr.io/kubernetools/mcp-server

快速开始

匿名模式（本地使用）

无需认证；所有连接按源 IP 在免费层限制下进行速率限制。

podman run -d \
  -p 3000:3000 \
  -e K8S_VERSIONS=v1.33 \
  ghcr.io/kubernetools/mcp-server:latest

使用 API 密钥认证

# 1. Create a key store file
echo '[{"key":"mykey","tier":"free"}]' > keys.json

# 2. Start the server
podman run -d \
  -p 3000:3000 \
  -v "$(pwd)/keys.json:/keys.json:ro" \
  -e K8S_VERSIONS=v1.33,v1.34,v1.35,v1.36 \
  -e KEY_STORE_PATH=/keys.json \
  ghcr.io/kubernetools/mcp-server:latest

配置

参数	环境变量	描述
Kubernetes 版本	K8S_VERSIONS	逗号分隔的预加载版本列表（例如 v1.33,v1.34）。默认为 v1.33。
GitHub 令牌	GITHUB_TOKEN	个人访问令牌（无需额外权限）。可选；将 GitHub API 速率限制从 60 次/小时提升至 5000 次/小时 — 加载多个版本时推荐使用。
密钥存储	KEY_STORE_PATH	API 密钥 JSON 文件的路径（将其挂载到容器中）。省略时，服务器以匿名模式运行：无需认证，所有连接按源 IP 在免费层限制下进行速率限制。
允许的主机	ALLOWED_HOSTS	逗号分隔的 Host 头值（例如 mcp.example.com,mcp.example.com:443）。省略时，主机验证被禁用 — 仅适用于本地开发。在生产环境中务必设置此项以防止 DNS 重绑定攻击。
浏览器重定向	BROWSER_REDIRECT_URL	将普通浏览器 GET 请求重定向到的 URL。MCP 客户端通过 Accept: text/event-stream 检测；浏览器将收到 307 到此 URL。省略时，浏览器 GET 请求返回 400。
日志级别	RUST_LOG	日志级别过滤器（例如 info、debug、mcp=debug）。
端口	--publish	服务器监听端口 3000。

认证

API 密钥存储

密钥存储是一个在启动时一次性加载的扁平 JSON 数组：

[
  { "key": "free-key-abc", "tier": "free" },
  { "key": "paid-key-xyz", "tier": "paid" }
]

每个请求必须在 Authorization 头中包含密钥：

Authorization: Bearer free-key-abc

没有有效密钥的请求将收到 401 Unauthorized。

匿名模式

当 KEY_STORE_PATH 未设置时，服务器无需认证即可运行。所有连接均被接受，并按源 IP 在免费层限制下进行速率限制。方便本地使用；请勿公开暴露。

层级和速率限制

层级	限制
free	10 次请求/分钟，突发 10
paid	约 1000 次请求/秒，突发 1000（实际上无限制）

超出限制的请求将收到 429 Too Many Requests。限制按 API 密钥跟踪，而非按 IP。

连接 MCP 客户端

服务器实现了 MCP 可流式 HTTP 传输。端点为：

http://<host>:<port>/[?version=<k8s-version>]

version 查询参数选择会话使用的 Kubernetes 版本。如果省略，则使用第一个加载的版本。未知版本将返回 400 Bad Request。

Claude Desktop

将以下内容添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "kubernetools": {
      "url": "http://localhost:3000/?version=v1.36",
      "headers": {
        "Authorization": "Bearer mykey"
      }
    }
  }
}

可用工具

list_resources

轻量级发现 — 每个资源返回一个条目，按 (group, kind, api_version) 排序。首先使用此工具查找种类名称。

可选过滤器： group（例如 "apps"、"core"）、api_version（例如 "v1"）。

get_resource

完整资源详情 — 字段、规范、状态和列表字段 — 足以在一次调用中编写清单。必需：kind。可选：group、api_version（默认为最新版本）。

具有非空 type_ref 和空 sub_fields 的字段应使用 get_type 深入查看。

get_type

深入查看通过 get_resource 输出中的 type_ref 引用的单个复合类型。必需：type_name（例如 "Container"、"PodFailurePolicy"）。

典型查询流程

list_resources                          → discover kind names and groups
  └─ get_resource(kind="Deployment")   → see all top-level fields + spec/status
       └─ get_type(type_name="...")    → drill into any complex type_ref

健康检查

GET /healthz 在端口 3000 上。

• 在 Kubernetes API 文档加载期间返回 503 Service Unavailable（正文：loading）。
• 服务器就绪后返回 200 OK（正文：ok）。

此端点绕过认证和速率限制。

将其用于启动、就绪和存活探针：

startupProbe:
  httpGet:
    path: /healthz
    port: 3000
  failureThreshold: 30   # allow up to 5 min for version loading
  periodSeconds: 10
readinessProbe:
  httpGet:
    path: /healthz
    port: 3000
livenessProbe:
  httpGet:
    path: /healthz
    port: 3000
  initialDelaySeconds: 10

错误响应

HTTP 状态码	原因
307 Temporary Redirect	设置了 BROWSER_REDIRECT_URL 时的浏览器 GET 请求
400 Bad Request	未设置 BROWSER_REDIRECT_URL 时的浏览器 GET 请求，或 version 参数指定的版本在启动时未加载
401 Unauthorized	缺少或无效的 Authorization: Bearer <key> 头
429 Too Many Requests	超出密钥层级的速率限制

MCP 级别的错误（未知工具名称、缺少必需参数、未找到种类）作为 MCP 错误内容在正常的 200 响应中返回。

示例

多个 Kubernetes 版本

podman run -d \
  -p 3000:3000 \
  -v "$(pwd)/keys.json:/keys.json:ro" \
  -e K8S_VERSIONS=v1.33,v1.34,v1.35,v1.36 \
  -e GITHUB_TOKEN=ghp_... \
  -e KEY_STORE_PATH=/keys.json \
  ghcr.io/kubernetools/mcp-server:latest

带主机验证的生产环境设置

podman run -d \
  -p 3000:3000 \
  -v "$(pwd)/keys.json:/keys.json:ro" \
  -e K8S_VERSIONS=v1.36 \
  -e KEY_STORE_PATH=/keys.json \
  -e ALLOWED_HOSTS=mcp.example.com,mcp.example.com:443 \
  -e BROWSER_REDIRECT_URL=https://example.com/docs \
  ghcr.io/kubernetools/mcp-server:latest

调试日志

podman run -d \
  -p 3000:3000 \
  -e K8S_VERSIONS=v1.33 \
  -e RUST_LOG=debug \
  ghcr.io/kubernetools/mcp-server:latest

固定到特定版本

podman run -d \
  -p 3000:3000 \
  -e K8S_VERSIONS=v1.33 \
  ghcr.io/kubernetools/mcp-server:0.1.0

镜像

基于 registry.access.redhat.com/hi/core-runtime:2.42-openssl 构建 — 一个最小化、无发行版的 glibc + OpenSSL 运行时。无 shell 或包管理器。