Kubernetes Resources Reference

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 次提高到 5 000 次——加载多个版本时建议设置。
密钥存储	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 识别；浏览器则会收到到此 URL 的 307 重定向。省略时，浏览器 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	每秒约 1 000 个请求，突发 1 000 个（实际上不受限制）

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

连接 MCP 客户端

该服务实现了 MCP Streamable HTTP transport。端点为：

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) 排序，为每个资源返回一条记录。首先使用此工具查找 kind 名称。

可选筛选条件： group（例如 "apps"、"core"）、api_version（例如 "v1"）。

get_resource

完整资源详情——字段、spec、status 和列表字段，足以通过一次调用编写清单。必填：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

健康检查

在端口 3000 上访问 GET /healthz。

• 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 级别的错误（未知工具名称、缺少必需参数、未找到 kind）会作为 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 或包管理器。