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회에서 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을 받습니다. 제한은 IP가 아닌 API 키별로 추적됩니다.

MCP 클라이언트 연결

서버는 MCP Streamable 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 (기본값은 가장 최근).

null이 아닌 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 수준 오류(알 수 없는 도구 이름, 필수 인수 누락, 종류를 찾을 수 없음)는 일반 200 응답 내에서 MCP 오류 콘텐츠로 반환됩니다.

예제

여러 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을 기반으로 빌드되었습니다 — 최소한의 distroless glibc + OpenSSL 런타임입니다. 셸이나 패키지 관리자가 없습니다.