talos-mcp

AI 에이전트(Claude Code, OpenAI Codex 및 모든 MCP 호환 클라이언트)에 Talos Linux 클러스터 관리 기능을 제공하는 MCP 서버입니다. talosctl 출력을 채팅에 붙여넣는 대신, 에이전트가 Talos gRPC API에서 직접 기계 판독 가능한 JSON을 반환하는 구조화된 도구를 호출하므로 중간 출력에 대한 토큰 비용이 발생하지 않습니다.

talosctl과 동일한 mTLS 자격 증명(~/.talos/config)을 사용하여 네이티브 Talos gRPC API를 통해 클러스터에 연결합니다.

설치

npm을 통한 설치 (Go 불필요, Linux/macOS, amd64/arm64):

npx talos-mcp

바이너리 다운로드 (Linux/macOS, amd64/arm64):

GitHub Releases에서 최신 릴리스를 다운로드하고 압축을 푼 뒤, 바이너리를 $PATH에 배치하세요.

소스에서 빌드 (Go 1.21+ 필요):

git clone https://github.com/Nosmoht/talos-mcp-server
cd talos-mcp
go build -o talos-mcp .

구성

기본적으로 ~/.talos/config(talosctl이 사용하는 동일한 파일)를 읽습니다. 환경 변수를 통해 재정의할 수 있습니다:

호환성

이 서버는 Talos Linux v1.9.x부터 v1.12.x까지 테스트되었습니다.

연결된 클러스터의 Talos 버전이 테스트 범위를 벗어나면 서버가 시작 시 경고를 기록합니다. 사용된 19개의 gRPC 메서드 모두 Talos v1.9 이후로 안정적입니다.

업그레이드 경로 유효성 검사

talos_upgrade 도구는 대상 버전이 Talos에서 지원하는 업그레이드 경로(한 번에 최대 하나의 마이너 버전, 예: v1.11.x → v1.12.x)를 따르는지 확인합니다. 마이너 버전을 건너뛰는 업그레이드는 오류와 함께 거부됩니다.

이미지가 사용자 지정 또는 팩토리 태그(예: factory.talos.dev/... 또는 :latest)를 사용하는 경우 태그를 구문 분석할 수 없어 유효성 검사가 자동으로 건너뜁니다. 유효성 검사를 명시적으로 우회하려면 TALOS_MCP_SKIP_VERSION_CHECK=true를 설정하세요.

클라이언트 설정

Claude Code

프로젝트의 .mcp.json에 추가하세요:

{
  "mcpServers": {
    "talos": {
      "command": "npx",
      "args": ["-y", "talos-mcp"]
    }
  }
}

또는 ~/.claude.json의 "mcpServers" 아래에 전역적으로 추가하세요. 로컬 바이너리를 선호하는 경우 "command": "npx"를 바이너리 경로로 바꾸세요.

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json에 추가하세요:

{
  "mcpServers": {
    "talos": {
      "command": "npx",
      "args": ["-y", "talos-mcp"]
    }
  }
}

OpenAI Codex

.codex/config.toml(프로젝트) 또는 ~/.codex/config.toml(전역)에 추가하세요:

[mcp_servers.talos]
command = "npx"
args = ["-y", "talos-mcp"]

[mcp_servers.talos.env]
TALOSCONFIG = "/path/to/talosconfig"

일반 MCP 클라이언트

이 서버는 stdio를 통해 MCP 프로토콜을 사용합니다:

./talos-mcp

도구

읽기 전용

변경 도구

이 도구들은 클러스터 상태를 수정하며 명시적인 안전 장치가 있습니다.

모든 도구는 선택적 nodes 필드(노드 IP 또는 호스트 이름 목록)를 허용합니다. 생략하면 talosconfig의 활성 컨텍스트가 사용됩니다.

보안 모델

신뢰 경계

MCP Client (Claude Code / Codex)
        │  stdio / JSON-RPC
        ▼
   talos-mcp  ◄── reads TALOSCONFIG (~/.talos/config)
        │  gRPC + mTLS
        ▼
  Talos API (each node)
        │
        ▼
    Node OS

데이터 흐름 경고: 도구 응답은 LLM의 컨텍스트 창으로 직접 흘러 들어가 LLM 제공업체로 전송됩니다. 도구가 반환하는 모든 것(노드 IP, 호스트 이름, 서비스 구성, 커널 로그, 파일 내용)은 네트워크를 통해 전송되는 프롬프트의 일부가 됩니다. LLM 제공업체에 전송하는 것이 불편한 데이터가 포함된 클러스터에는 이 서버를 사용하지 마십시오.

Talos RBAC는 서버 측에서 적용됩니다. talosconfig의 자격 증명에 따라 각 노드에서 허용되는 작업이 결정됩니다. talos-mcp는 Talos RBAC를 우회할 수 없습니다. API가 거부하는 요청은 오류와 함께 실패하며 조용히 성공하지 않습니다.

도구 분류 및 최소 필수 RBAC 역할

안전 메커니즘

위협 모델에 포함되지 않는 것

• LLM 자체 — 프롬프트 인젝션, 환각된 도구 인수 및 LLM 제공업체의 데이터 보존은 이 서버의 범위를 벗어납니다

• MCP 클라이언트 — Claude Code, Codex 또는 기타 MCP 클라이언트의 보안은 해당 프로젝트의 책임입니다

• talos-mcp와 Talos 노드 간의 네트워크 경로 — talosconfig의 자격 증명을 사용하는 상호 TLS로 보호됩니다

최소 권한 자격 증명 설정

이 서버와 함께 사용할 최소 권한을 가진 전용 talosconfig를 만드세요:

읽기 전용 액세스 (대부분의 사용 사례에 권장):

# Generate a reader-only talosconfig
talosctl config new --roles=os:reader talosconfig-readonly

그런 다음 최대 제한을 위해 TALOSCONFIG=/path/to/talosconfig-readonly 및 TALOS_MCP_READ_ONLY=true를 설정하세요. 이 설정으로 서버는 읽기 전용 도구만 노출하며, 도구가 어떻게든 우회되더라도 자격 증명은 어떠한 변경 작업도 수행할 수 없습니다.

운영자 액세스 (서비스 관리, 재부팅, 업그레이드용):

talosctl config new --roles=os:operator talosconfig-operator

이는 talos_patch_config(os:admin 필요)를 제외한 모든 도구를 포함합니다.

전체 액세스 (구성 패치에 필요):

기본 talosconfig를 사용하거나 os:admin으로 생성하세요. 구성 패치 기능이 명시적으로 필요한 설정에만 예약하세요.

다운로드 확인

체크섬 (무결성)

각 릴리스에는 모든 아카이브의 SHA-256 해시가 포함된 talos-mcp_<version>_checksums.txt 파일이 포함되어 있습니다. 다운로드 후 바이너리를 확인하세요:

# Download archive and checksums
curl -LO https://github.com/Nosmoht/talos-mcp-server/releases/download/v<version>/talos-mcp_<version>_linux_amd64.tar.gz
curl -LO https://github.com/Nosmoht/talos-mcp-server/releases/download/v<version>/talos-mcp_<version>_checksums.txt

# Verify
sha256sum --check --ignore-missing talos-mcp_<version>_checksums.txt

이는 손상되거나 잘린 다운로드를 감지합니다. 손상된 릴리스 파이프라인으로부터 보호하지는 않습니다.

GitHub 아티팩트 증명 (SLSA L2 출처)

각 릴리스에는 바이너리를 생성한 특정 커밋 및 워크플로 실행에 암호화 방식으로 연결되는 GitHub 네이티브 빌드 출처 증명이 포함되어 있습니다:

gh attestation verify talos-mcp_<version>_linux_amd64.tar.gz \
  --repo Nosmoht/talos-mcp-server

이 작업에는 GitHub CLI가 필요합니다. 확인을 통과하면 아티팩트가 타사 빌드가 아닌 이 리포지토리의 공식 릴리스 워크플로에 의해 생성되었음을 의미합니다.

npm 패키지 출처

npm 패키지는 출처 증명과 함께 게시됩니다:

npm audit signatures

통과 결과는 패키지가 OIDC 신뢰 게시를 통해 공식 GitHub Actions 릴리스 워크플로에 의해 게시되었음을 의미합니다.

개발

# Build
go build -o talos-mcp .

# Test
go test -race ./...

# Lint (requires golangci-lint v2)
golangci-lint run

# Format check
gofmt -l .

라이선스

MIT