kubernetools MCP Server

kubernetools/mcp-server

Ảnh container cho máy chủ MCP kubernetools.

Registry: ghcr.io/kubernetools/mcp-server

Bắt đầu nhanh

Chế độ ẩn danh (sử dụng cục bộ)

Không yêu cầu xác thực; tất cả kết nối đều bị giới hạn tốc độ theo IP nguồn ở mức giới hạn gói miễn phí.

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

Với xác thực khóa 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

Cấu hình

Tham số	Biến môi trường	Mô tả
Phiên bản Kubernetes	K8S_VERSIONS	Danh sách các phiên bản được phân tách bằng dấu phẩy để tải trước (ví dụ: v1.33,v1.34). Mặc định là v1.33.
GitHub token	GITHUB_TOKEN	Mã thông báo truy cập cá nhân (không cần thêm phạm vi). Tùy chọn; tăng giới hạn tốc độ API GitHub từ 60 lên 5.000 yêu cầu/giờ — được khuyến nghị khi tải nhiều phiên bản.
Kho khóa	KEY_STORE_PATH	Đường dẫn đến tệp JSON khóa API (gắn nó vào container). Khi bỏ qua, máy chủ chạy ở chế độ ẩn danh: không yêu cầu xác thực và tất cả kết nối đều bị giới hạn tốc độ theo IP nguồn ở mức giới hạn gói miễn phí.
Máy chủ được phép	ALLOWED_HOSTS	Danh sách các giá trị tiêu đề Host được phân tách bằng dấu phẩy để chấp nhận (ví dụ: mcp.example.com,mcp.example.com:443). Khi bỏ qua, xác thực máy chủ bị vô hiệu hóa — chỉ phù hợp cho phát triển cục bộ. Luôn đặt giá trị này trong môi trường production để ngăn chặn tấn công DNS-rebinding.
Chuyển hướng trình duyệt	BROWSER_REDIRECT_URL	URL để chuyển hướng các yêu cầu GET thông thường từ trình duyệt đến. Máy khách MCP được phát hiện bởi Accept: text/event-stream; trình duyệt nhận được 307 đến URL này thay thế. Khi bỏ qua, GET từ trình duyệt trả về 400.
Mức nhật ký	RUST_LOG	Bộ lọc mức nhật ký (ví dụ: info, debug, mcp=debug).
Cổng	--publish	Máy chủ lắng nghe trên cổng 3000.

Xác thực

Kho khóa API

Kho khóa là một mảng JSON phẳng được tải một lần khi khởi động:

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

Mỗi yêu cầu phải bao gồm khóa trong tiêu đề Authorization:

Authorization: Bearer free-key-abc

Yêu cầu không có khóa hợp lệ sẽ nhận được 401 Unauthorized.

Chế độ ẩn danh

Khi KEY_STORE_PATH không được đặt, máy chủ chạy mà không cần xác thực. Tất cả kết nối được chấp nhận và bị giới hạn tốc độ theo IP nguồn ở mức giới hạn gói miễn phí. Thuận tiện cho sử dụng cục bộ; không công khai ra bên ngoài.

Các gói và giới hạn tốc độ

Gói	Giới hạn
free	10 yêu cầu / phút, bùng nổ 10
paid	~1.000 yêu cầu / giây, bùng nổ 1.000 (thực tế không giới hạn)

Yêu cầu vượt quá giới hạn sẽ nhận được 429 Too Many Requests. Giới hạn được theo dõi theo khóa API, không phải theo IP.

Kết nối máy khách MCP

Máy chủ triển khai MCP Streamable HTTP transport. Điểm cuối là:

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

Tham số truy vấn version chọn phiên bản Kubernetes nào sẽ sử dụng cho phiên làm việc. Nếu bỏ qua, phiên bản được tải đầu tiên sẽ được sử dụng. Phiên bản không xác định trả về 400 Bad Request.

Claude Desktop

Thêm phần sau vào claude_desktop_config.json:

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

Công cụ có sẵn

list_resources

Khám phá nhẹ — trả về một mục cho mỗi tài nguyên, được sắp xếp theo (group, kind, api_version). Sử dụng công cụ này trước để tìm tên loại.

Bộ lọc tùy chọn: group (ví dụ: "apps", "core"), api_version (ví dụ: "v1").

get_resource

Chi tiết tài nguyên đầy đủ — trường, spec, trạng thái và trường danh sách — đủ để viết một manifest trong một lần gọi. Bắt buộc: kind. Tùy chọn: group, api_version (mặc định là gần đây nhất).

Các trường có type_ref không null và sub_fields trống nên được đào sâu bằng get_type.

get_type

Đào sâu vào một loại tổng hợp duy nhất được tham chiếu qua type_ref trong đầu ra get_resource. Bắt buộc: type_name (ví dụ: "Container", "PodFailurePolicy").

Luồng truy vấn điển hình

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

Kiểm tra sức khỏe

GET /healthz trên cổng 3000.

• Trả về 503 Service Unavailable (body: loading) trong khi tài liệu API Kubernetes đang tải.
• Trả về 200 OK (body: ok) khi máy chủ đã sẵn sàng.

Điểm cuối này bỏ qua xác thực và giới hạn tốc độ.

Sử dụng nó cho các đầu dò khởi động, sẵn sàng và sống:

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

Phản hồi lỗi

Mã trạng thái HTTP	Nguyên nhân
307 Temporary Redirect	GET từ trình duyệt khi BROWSER_REDIRECT_URL được đặt
400 Bad Request	GET từ trình duyệt khi BROWSER_REDIRECT_URL không được đặt, hoặc tham số version đặt tên phiên bản không được tải khi khởi động
401 Unauthorized	Thiếu hoặc tiêu đề Authorization: Bearer <key> không hợp lệ
429 Too Many Requests	Vượt quá giới hạn tốc độ cho gói của khóa

Lỗi cấp MCP (tên công cụ không xác định, thiếu đối số bắt buộc, không tìm thấy loại) được trả về dưới dạng nội dung lỗi MCP bên trong phản hồi 200 bình thường.

Ví dụ

Nhiều phiên bản 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

Thiết lập production với xác thực máy chủ

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

Ghi nhật ký gỡ lỗi

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

Ghim vào một bản phát hành cụ thể

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

Ảnh

Được xây dựng trên registry.access.redhat.com/hi/core-runtime:2.42-openssl — một runtime glibc + OpenSSL tối giản, không phân phối. Không có shell hoặc trình quản lý gói.