홈랩 MCP 서버

Python 3.12+ License: MIT

Model Context Protocol을 통한 AI 기반 홈랩 인프라 관리

AI 어시스턴트가 홈랩 인프라를 관리, 배포 및 모니터링할 수 있게 해주는 Python MCP 서버입니다. SSH 탐색, VM 관리, 서비스 설치, 네트워크 토폴로지 매핑, Proxmox 운영 및 자격 증명 관리 기능을 제공합니다.

주요 기능

SSH 탐색 -- 모든 시스템에서 포괄적인 하드웨어 및 소프트웨어 정보 수집
서비스 설치 -- 템플릿을 사용하여 Jellyfin, Pi-hole, Ollama, Home Assistant 등을 배포
Proxmox 통합 -- 전체 API 액세스 및 커뮤니티 스크립트 탐색
VM/컨테이너 수명 주기 -- Docker 및 LXD 워크로드 배포, 제어 및 제거
네트워크 매핑 -- 장치 탐색, 토폴로지 분석 및 변경 사항 추적
Terraform 및 Ansible -- 드리프트 감지 및 플레이북을 통한 상태 관리형 배포
자격 증명 관리 -- 서버를 한 번 등록하면 자격 증명을 다시 입력할 필요 없이 연결

빠른 시작

# Install from PyPI (recommended — no clone needed)
uvx homelab-mcp

# Or clone and run from source
git clone https://github.com/washyu/homelab_mcp.git
cd homelab_mcp
uv sync && uv run python run_server.py

전체 단계별 가이드(환경 변수, MCP 클라이언트 구성, 첫 번째 도구 호출)는 설정 가이드를 참조하세요.

문서

가이드	설명
설정 가이드	시작부터 첫 번째 도구 호출까지
도구 참조	인수 및 예제가 포함된 모든 도구
구성	환경 변수 및 CLI 옵션
Claude Desktop 설정	Claude Desktop 통합 가이드

작동 원리

설정 -- 서버가 처음 실행될 때 SSH 키 쌍(~/.ssh/mcp_admin_rsa)을 생성합니다.
호스트 온보딩 -- setup_mcp_admin을 사용하여 대상 시스템에 관리형 사용자를 생성합니다.
확인 -- verify_mcp_admin을 사용하여 비밀번호 없는 SSH 액세스를 확인합니다.
관리 -- 하드웨어 탐색, 서비스 설치, VM 제어 및 네트워크 매핑을 수행합니다.

서버는 MCP 프로토콜을 사용하여 stdio를 통해 통신합니다. MCP 호환 클라이언트(Claude Desktop 등)에 연결하고 자연어로 상호 작용하세요.

자격 증명 관리

SSH 및 Proxmox 자격 증명을 한 번 저장하면 서버가 모든 연결 시 자동으로 주입합니다:

# Store an SSH credential
homelab-mcp credentials add 192.168.1.10 admin

# Store a Proxmox API credential
homelab-mcp credentials add 192.168.1.200 root@pam --type proxmox

# List stored credentials
homelab-mcp credentials list
homelab-mcp credentials list --type proxmox

# Remove a credential
homelab-mcp credentials remove 192.168.1.10

자격 증명은 OS 키링(Linux의 경우 libsecret, macOS의 경우 Keychain)에 저장됩니다. OS 키링을 사용할 수 없는 경우(헤드리스 서버), 자격 증명은 환경 변수로 대체됩니다.

전체 문서는 자격 증명 CLI 참조를 확인하세요.

MCP 클라이언트 구성

PyPI (uvx) 사용 — 권장:

{
  "mcpServers": {
    "homelab": {
      "command": "uvx",
      "args": ["homelab-mcp"]
    }
  }
}

소스 클론 사용:

{
  "mcpServers": {
    "homelab": {
      "command": "uv",
      "args": ["run", "python", "run_server.py"],
      "cwd": "/path/to/homelab_mcp"
    }
  }
}

개발

# Install with dev dependencies
uv sync --group dev

# Run tests (unit only, no Docker required)
uv run pytest tests/ -m "not integration"

# Code quality
uv run ruff check src/ tests/
uv run mypy src/

프로덕션 배포 세부 정보는 DEPLOYMENT.md를 참조하세요.

프로젝트 구조

src/homelab_mcp/
  server.py              # MCP server with JSON-RPC protocol
  tool_schemas/          # Tool definitions (8 schema files)
  tool_annotations.py    # MCP annotation hints per tool
  ssh_tools.py           # SSH discovery and hardware detection
  service_installer.py   # Service installation framework
  infrastructure_crud.py # Infrastructure lifecycle management
  vm_operations.py       # VM/container operations
  sitemap.py             # Network topology mapping
  database.py            # SQLite device tracking
  error_handling.py      # Centralized error handling
  credential_store.py    # OS keyring credential storage
  log_filter.py          # Credential redaction for log output
  prompt_registry.py     # MCP prompts registry
  resource_readers.py    # MCP resource read handlers
  service_templates/     # YAML service definitions
tests/                   # Unit and integration tests
docs/                    # Full documentation

감사의 말

Proxmox 커뮤니티 스크립트 통합은 community-scripts/ProxmoxVE (MIT 라이선스)를 기반으로 합니다.

기여

저장소를 포크합니다.
기능 브랜치를 생성합니다.
새로운 기능에 대한 테스트를 작성합니다.
모든 테스트가 통과하는지 확인합니다.
풀 리퀘스트를 제출합니다.

라이선스

MIT 라이선스 -- 자세한 내용은 LICENSE 파일을 참조하세요.

Homelab MCP Server

홈랩 MCP 서버

주요 기능

빠른 시작

문서

작동 원리

자격 증명 관리

MCP 클라이언트 구성

개발

프로젝트 구조

감사의 말

기여

라이선스

Resources

Looking for Admin?

Tools

Latest Blog Posts

MCP directory API