K8s 클러스터 운영 MCP Server

FastMCP 기반의 Kubernetes 운영 조회 MCP 서비스입니다. kubectl get / describe / logs / events --watch 등의 일상적인 트러블슈팅 동작을 LLM이 호출할 수 있는 읽기 전용 도구로 캡슐화하여 Claude 등 클라이언트가 클러스터 상태를 직접 읽고 장애 현장을 파악할 수 있게 합니다.

⚠️ 이 프로젝트는 읽기 전용 도구만 노출합니다(create/update/delete 없음). 그러나 여전히 읽기 전용 ServiceAccount RBAC와 함께 사용할 것을 권장합니다. 아래 '보안 권장사항'을 참조하세요.

도구 목록

추가로 @mcp.prompt(노드 트러블슈팅 / 클러스터 점검 안내)와 @mcp.resource(k8s://cluster/summary 클러스터 요약) 두 가지 부가 기능이 있습니다.

Related MCP server: k8s-readonly-mcp

디렉터리 구조

├── 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/              # 单元测试

설치 및 실행

# 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

테스트 실행

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

구성

모든 설정은 환경 변수를 통해 이루어지며 기본값이 있습니다(config.py 참조):

K8s 연결 구성 로드 우선순위: in-cluster(Pod 내 SA) → 명시적 KUBECONFIG_PATH → 공식 kubeconfig 해석 체인이며, 단일 진실 공급원으로 여러 파일에서 조합하지 않습니다.

MCP 클라이언트 연동

Claude Code를 예로 들면(HTTP transport가 127.0.0.1:8081에서 실행 중일 때):

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

보안 권장사항

1. 읽기 전용 RBAC 사용: 이 서비스를 실행하는 Pod / 사용자에게 읽기 전용 ClusterRole을 구성하여 고권한 자격 증명을 빌려 쓰지 않도록 합니다.

2. 기본적으로 로컬에만 바인딩: MCP_HOST 기본값은 127.0.0.1입니다. 외부에 노출해야 한다면 반드시 리버스 프록시 계층에서 인증(TLS + Token / OIDC)을 추가하세요. HTTP transport 자체에는 인증과 속도 제한이 없기 때문입니다.

3. 인증서 검증을 끄지 마세요: K8S_VERIFY_SSL=false는 자체 서명 인증서를 임시 디버깅할 때만 사용하고, 프로덕션 환경에서는 true를 유지하세요.

4. 자격 증명을 저장소에 넣지 마세요: kubeconfig에는 비밀 키가 포함되어 있습니다. .gitignore에 kubeconfig*가 이미 제외되어 있으니 강제로 커밋하지 마세요.

알려진 제한 사항

• 모든 도구는 읽기 전용이며 변경 작업이 없습니다(의도적인 설계입니다).

• watch_* 계열은 전역 동시성 잠금의 제한을 받습니다. 동시에 하나의 watch만 실행할 수 있어 API Server에 부하를 주지 않습니다.

• 이벤트/로그 출력에는 길이 상한이 있어 초과하는 내용은 잘립니다(read_pod_log의 잘림 로직과 query_events의 max_count 참조).