MCP Hub

하나의 MCP 서버로 AI 어시스턴트에게 전체 홈랩의 열쇠를 제공하세요.

MCP Hub는 네트워크의 한 머신에 위치하여 Model Context Protocol 서버 역할을 하며, 여기서부터 확장됩니다: 플릿의 모든 호스트로 SSH, Proxmox 컨테이너, Docker, Synology DSM, Cloudflare 터널 및 DNS, n8n 워크플로우, Notion, 비밀번호 저장소. 수십 개의 MCP 서버를 실행하고 각각을 클라이언트에 연결하는 대신, 하나만 실행하고 어시스턴트를 그곳에 연결하세요.

"왜 Jellyfin에 연결할 수 없지?" — 그러면 어시스턴트가 컨테이너를 확인하고, 저널을 읽고, 터널 인그레스가 오래되었음을 발견하고, 수정한 후, 수행한 작업을 알려줍니다.

⚠️ 배포하기 전에 SECURITY.md를 읽으십시오. MCP Hub는 LLM에게 플릿 전체에 대한 루트 셸 액세스 권한을 부여합니다. 이것이 바로 이 도구의 목적이며, 진정으로 위험합니다. 기본값은 안전합니다(127.0.0.1, 읽기 전용). 위험은 기본값을 변경할 때 시작됩니다.

문제 해결 데모

저장소에는 완전하고 관찰 우선의 문제 해결 세션에 대한 익명화된 Asciinema 녹화가 포함되어 있습니다: 실패한 엔드포인트, systemd 진단, 정확한 변경 계획, 명시적 확인, 재시작, 최종 상태 점검. 예제 인벤토리를 사용하며 개인 인프라 데이터를 포함하지 않습니다.

asciinema play docs/troubleshooting.cast

Asciinema가 설치되지 않은 경우 녹화를 직접 확인하십시오. 캐스트 형식은 개행으로 구분된 JSON이며 검토 가능합니다.

Related MCP server: homelab-mcp

목차

• 기능

• 빠른 시작

• 배포

• 로컬 테스트

• 복구 진단

• 설정

• 도구 참조

• 보안

• 버전 관리

• 기여

기능

• 111개 도구, 하나의 엔드포인트, 하나의 설정 파일.

• 설정 기반. 네트워크는 hosts.yaml과 .env에 있습니다. 인프라에 대한 어떤 것도 코드에 포함되지 않습니다.

• 다중화 SSH. 지속적인 제어 소켓을 사용하여 플릿 전체 명령이 TCP 핸드셰이크 대신 밀리초 단위로 실행됩니다.

• 선택적 통합. 모든 통합은 기본적으로 비활성화되어 있으며 단일 플래그로 활성화됩니다. 원하는 경우 순수 SSH 플릿 도구로 실행할 수 있습니다.

• 플러그형 비밀. 환경 또는 bw serve를 통한 Bitwarden/Vaultwarden 저장소에서 자격 증명을 읽습니다.

• 추측 불가능한 엔드포인트 경로 기반 Bearer 토큰 인증.

• 전역 읽기 전용 모드, 기본적으로 활성화됨: 하나의 플래그로 43개의 변경 도구를 모두 비활성화하며, 도구별이 아닌 중앙에서 적용됩니다.

• 파일 읽기 및 명령 출력에서 자동 비밀 수정.

• 폴링, 로그 및 영구 SQLite 상태 저장소를 사용한 백그라운드 작업.

빠른 시작

Python 3.11+ 및 관리하려는 머신에 SSH 액세스 권한이 있는 Linux 호스트가 필요합니다.

git clone https://github.com/wnx82/mcp-hub.git
cd mcp-hub

python3 -m venv .venv && . .venv/bin/activate
pip install -e .

cp .env.example .env                  # then edit — see below
cp hosts.example.yaml hosts.yaml      # then edit: your fleet
chmod 600 .env hosts.yaml

python server.py

최소한 .env에서 다음 두 가지를 설정하십시오:

MCP_SECRET_PATH=/$(openssl rand -hex 16)   # unguessable endpoint path
MCP_AUTH_TOKEN=$(openssl rand -hex 32)     # bearer token — the real auth

그러면 서버는 MCP_READ_ONLY=true 상태로 http://127.0.0.1:8000<MCP_SECRET_PATH>에서 수신 대기합니다. MCP 클라이언트를 해당 URL로 지정하고 Authorization: Bearer <MCP_AUTH_TOKEN>을 보내십시오. 토큰이 없는 요청은 401을 받고, 다른 경로에 대한 요청은 404를 받습니다.

HTTP 대신 stdio를 원하는 로컬 MCP 클라이언트의 경우, 다음으로 동일한 허브를 시작하십시오:

mcp-hub --transport stdio

또는 실행 전에 환경에서 MCP_TRANSPORT=stdio를 설정하십시오.

systemd 배포의 경우, sudo ./deploy/install.sh는 전용 mcphub 사용자와 SSH 키를 생성하고, 두 비밀을 /etc/default/mcp-hub에 생성하며, 유닛을 설치합니다. 이는 멱등적이며 기존 설정을 덮어쓰지 않습니다. deploy/를 참조하십시오.

완전한 Claude Code 설정, 안전한 토큰 처리, 연결 확인, 첫 번째 읽기 전용 프롬프트 및 현재 Claude Desktop 제한 사항에 대해서는 MCP Hub를 Claude에 연결 을 참조하십시오.

어시스턴트가 개인 토폴로지, 호스트 역할, 변경 창 및 MCP 운영 규칙을 해당 데이터를 커밋하지 않고 이해하도록 하려면 PROJECT_INSTRUCTIONS.example.md에서 시작하여 사용자 정의된 PROJECT_INSTRUCTIONS.md를 로컬 전용으로 유지하십시오.

배포

MCP Hub는 세 가지 실행 모드를 지원합니다:

Python 패키지 및 직접 실행은 현재 체크아웃과 해당 가상 환경을 사용합니다. 서비스 계정, SSH 키, 환경 파일 또는 재시작 정책을 생성하지 않습니다. systemd 설치 프로그램은 이러한 운영 구성 요소를 프로비저닝하고, 재실행 시 로컬 구성을 그대로 유지하며, 허브 가상 환경 외부에 Rescue를 설치합니다.

컨테이너 이미지는 아직 공식 배포 대상이 아닙니다. 허브는 네트워크 액세스, SSH ID, 영구 state.db 및 로컬 인벤토리에 대한 액세스가 필요합니다. 컨테이너에 패키징하는 운영자는 이러한 속성을 직접 유지해야 합니다.

현재 요구 사항과 공식 이미지가 권장되기 전에 보장해야 하는 사항은 docs/docker-packaging.md를 참조하십시오.

로컬 테스트

기여자 중심의 린트, 단위 테스트, 도구 등록, 생성된 문서, 설치 프로그램 스모크 테스트 및 수동 읽기 전용 실행 체크리스트는 docs/testing-local.md 를 참조하십시오.

MCP 2026-07-28 마이그레이션 요약, 호환성 매트릭스 및 롤백 절차는 docs/migration/mcp-2026-07-28-guide.md 를 참조하십시오.

PR을 열거나 브랜치를 게시하기 전에 로컬 릴리스 준비 상태 확인을 실행할 수도 있습니다:

python3 scripts/check_repo_hygiene.py
python3 scripts/check_tool_annotations.py
python3 scripts/check_security_readiness.py

보안 준비 상태 확인을 푸시 시 Git에 자동으로 연결하려면:

./scripts/install_pre_push_hook.sh

아키텍처

server.py는 MCP 서버 구성 루트로 유지되며 도메인 코드는 점진적으로 tools/로 이동 중입니다. SSH 명령 구성, Cloudflare 경로 및 응답 추출, DSM 프로토콜 메타데이터, 인벤토리 및 플레이북 빌더는 이미 분리되었습니다. tools/registry.py는 추출된 도구를 도메인에 할당합니다. 해당 도메인은 각 감사 요약에 포함됩니다. 새로운 프로토콜 로직은 해당 도메인 모듈에 있어야 하며 server.py를 가져와서는 안 됩니다.

향후 통합은 docs/integration-evaluation.md에서 최소 권한 범위 및 승격 게이트와 함께 우선 순위가 지정됩니다.

복구 진단

mcp-hub-rescue는 기본 서버를 가져올 수 없거나 가상 환경이 손상된 경우에도 계속 작동하도록 설계된 읽기 전용 로컬 CLI입니다. systemd 설치 프로그램은 이를 /opt/mcp-hub-rescue에 복사하고 MCP Hub 프로세스 및 가상 환경 외부의 시스템 Python으로 실행합니다.

sudo mcp-hub-rescue doctor
sudo mcp-hub-rescue status
sudo mcp-hub-rescue health
sudo mcp-hub-rescue logs --lines 50
sudo mcp-hub-rescue validate-config

결과는 구조화된 JSON입니다. Rescue는 server.py, tools/*, MCP 또는 선택적 통합을 절대 가져오지 않으며, 이 경계는 CI에 의해 적용됩니다. 현재 명령은 관찰 및 진단만 수행합니다. 재시작, 복구 및 롤백 작업은 확인 및 마지막으로 알려진 정상 상태 보호 장치와 함께 별도로 추가될 예정입니다.

설정

모두 git에서 무시됨 — 각각 추적된 .example 템플릿이 있습니다:

호스트 항목은 설계상 최소입니다:

hosts:
  nas:
    hostname: nas.example.lan
    user: admin
    role: storage
    tags: [nas, backup]
    mac: "aa:bb:cc:dd:ee:01"   # optional, enables wake_host()

태그는 그룹을 지정하는 방법입니다: fleet_exec(tag="backup", command="df -h"). 복사 가능한 두 호스트 인벤토리는 docs/examples/hosts.minimal.yaml에서 시작하십시오. 더 큰 hosts.example.yaml은 지원되는 모든 호스트 옵션을 보여줍니다.

docs/examples/topology.guarded.yaml과 함께 사용하여 Proxmox 게스트를 매핑하고, 오래된 주소 트랩을 기록하고, 함부로 변경해서는 안 되는 인프라를 표시하십시오. _do_not_touch 항목은 어시스턴트를 위한 운영 컨텍스트이지, 강제된 액세스 제어 경계가 아닙니다. 기술적 시행을 위해 토큰 프로필 및 호스트 제한을 사용하십시오.

docs/examples/endpoints.minimal.yaml을 추가하여 항상 켜져 있거나 간헐적인 HTTP 서비스를 모니터링하십시오. 일반 세트에 대해서는 endpoints_health()를 호출하고, 일반적으로 전원이 꺼져 있을 수 있는 서비스를 포함하려면 endpoints_health(include_intermittent=true)를 호출하십시오. 200에서 399까지의 응답은 정상으로 간주됩니다. 리디렉션은 따르지 않습니다.

전체 기본값, 제한, 통합 설정 및 비밀 처리 참고 사항은 환경 변수 참조 에 있습니다.

추적된 예제를 개인적이고 추적되지 않는 PROJECT_INSTRUCTIONS.md와 함께 사용하여 어시스턴트가 저장소에 있어서는 안 되는 토폴로지 주의 사항, 유지 관리 기간, 명명 규칙 및 "건드리지 말아야 할" 지침을 볼 수 있도록 하십시오.

도구 참조

모든 도구는 동일한 최상위 봉투를 반환합니다:

{
  "ok": true,
  "data": {},
  "error": null,
  "duration_ms": 12,
  "host": "example",
  "request_id": "4d52b1f69b974b7784bf65dd",
  "tool": "system_info"
}

data에는 도구별 페이로드가 포함됩니다. 보안 거부 및 제어된 예외는 ok: false와 동일한 형태를 사용하여 연결된 호출 및 감사 상관 관계를 예측 가능하게 만듭니다.

중앙 도구 래퍼는 또한 요청 크기, 토큰당 호출 수, 대상당 동시 호출 수, 반복된 대상 실패 및 변경 빈도를 제한합니다. 기본값은 .env.example에 문서화되어 있습니다. 제한 거부는 다른 모든 호출과 동일한 응답 봉투 및 감사 추적을 사용합니다.

**완전한 생성 도구 참조**는 각 그룹을 각 도구의 정확한 시그니처와 모델 대상 설명이 포함된 표로 확장합니다. CI는 등록된 함수에 대해 이를 검증합니다.

안내 진단은 항상 관찰 후 중단됩니다. 증거, 평가 및 correction_applied: false와 함께 제안된 다음 단계를 반환합니다. check_backup_chain은 신선도 및 저장소 신호일 뿐이며, 복원이 성공할 것이라는 증거는 아닙니다.

보안

MCP Hub는 설계상 원격 코드 실행 서비스입니다. 노출하기 전에:

• 기본 127.0.0.1 바인딩을 유지하거나 액세스 정책이 있는 터널 뒤에 배치하세요.

• MCP_AUTH_TOKEN을 설정하세요. 비밀 URL 경로는 난독화일 뿐, 인증이 아닙니다.

• 모델이 이를 사용하여 수행하는 작업을 신뢰할 때까지 MCP_READ_ONLY=true를 유지하세요.

• 리소스 가드 기본값을 활성화 상태로 유지한 다음, 비활성화하지 않고 관찰된 감사 트래픽에서 조정하세요.

• 전용 SSH 키와 최소한의 hosts.yaml을 제공하세요.

전체 위협 모델, 강화 가이드 및 취약점 보고: SECURITY.md.

로컬 사전 게시 체크리스트와 푸시 전에 일반적인 비밀 유출 실수를 잡아내는 선택적 Git 훅은 scripts/check_security_readiness.py 및 scripts/install_pre_push_hook.sh를 참조하세요.

버전 관리

SemVer. 1.0 이전에서는 주요 변경 사항이 부 버전을 올리므로, 업그레이드 전에 Changed 및 Removed 노트를 읽으세요. _version.py는 단일 진실 공급원입니다. 실행 중인 서버는 mcp-hub --version, MCP 핸드셰이크, 그리고 mcp_health에서 이를 보고합니다.

모든 릴리스는 **CHANGELOG.md**에 문서화되어 있으며, 보안 관련 변경 사항은 자체 섹션에 명시됩니다.

기여

이슈 및 풀 리퀘스트를 환영합니다. 특히 버그 신고, 새로운 통합, 문서 수정을 환영합니다. CONTRIBUTING.md를 참조하세요.

라이선스

MIT © wnx82