Unraid MCP 서버

AI 어시스턴트가 공식 Unraid GraphQL API를 통해 Unraid 서버와 상호 작용할 수 있도록 하는 Python 기반 MCP(Model Context Protocol) 서버입니다.

부인 성명

사용 시 모든 책임은 사용자에게 있습니다 . 이 소프트웨어는 AI 비서를 통해 Unraid 서버에 접근할 수 있도록 합니다. 보안 강화를 위해 이 구현은 읽기 전용 으로 설정되어 있지만, 사용 시 주의가 필요합니다.

• 이는 비공식적인 도구이며 Unraid, Inc.와 제휴하거나 보증을 받지 않았습니다.
• 모든 작업은 시스템 수정을 방지하기 위해 읽기 전용 작업으로 제한됩니다.
• 항상 데이터의 적절한 백업을 유지하세요
• 조치를 취하기 전에 AI 도우미가 제공하는 모든 정보와 제안을 검토하세요.
• 개발자는 이 소프트웨어 사용으로 인해 발생할 수 있는 문제에 대해 책임을 지지 않습니다.

읽기 전용 액세스 권한이 있더라도 모니터링 도구는 민감한 시스템 정보를 노출할 가능성이 있습니다. 이 소프트웨어를 사용함으로써 귀하는 이러한 제한 사항과 위험을 인지하고 이에 동의합니다.

특징

• 시스템 정보 : Unraid 서버에 대한 자세한 정보를 얻으세요
• 어레이 관리 : 어레이 상태 모니터링
• Docker 관리 : Docker 컨테이너 및 네트워크 나열
• VM 관리 : 가상 머신 목록
• 디스크 정보 : 디스크 및 할당되지 않은 장치에 대한 자세한 정보를 가져옵니다.
• 알림 관리 : 시스템 알림을 보고 관리합니다.
• 공유 관리 : 네트워크 공유를 보고 관리합니다.
• 사용자 관리 : 사용자 목록
• API 키 관리 : API 키 목록
• 패리티 기록 : 패리티 검사 기록 보기
• 공유 : Unraid 서버에서 사용자 공유를 탐색합니다.
• 플러그인 : 설치된 플러그인과 해당 상태를 확인합니다.
• 오류 처리 : 진단 정보를 통한 포괄적인 오류 처리
• 로깅 : 문제 해결을 위한 자세한 로깅
• 템플릿 리소스 : 이름으로 특정 컨테이너 및 VM에 액세스

필수 조건

• Python 3.10 이상
• API가 활성화된 Unraid 서버
• 적절한 권한이 있는 API 키

설치

Smithery를 통해 설치

Smithery를 통해 Claude Desktop에 Unraid MCP 서버를 자동으로 설치하려면:

지엑스피1

수동 설치

1. 저장소를 복제합니다.
   git clone https://github.com/jmagar/unraid-mcp.git cd unraid-mcp
2. 가상 환경을 만들고 활성화하세요.
   python3 -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate
3. 종속성 설치:
   pip install -r requirements.txt
4. Unraid API 자격 증명으로 .env 파일을 만듭니다.
   cp .env.template .env # Edit .env with your actual API URL and key

Unraid API 설정

이 MCP 서버를 사용하려면 Unraid 서버에서 Unraid API를 설정해야 합니다.

1. CLI를 사용하여 개발자 모드와 GraphQL 샌드박스를 활성화합니다.
   unraid-api developer
   화면의 지시에 따라 샌드박스를 활성화하세요.
2. 필요한 권한이 있는 API 키를 만듭니다.
   unraid-api apikey --create
   화면의 지시에 따라 이름, 설명, 역할, 권한을 설정하세요.
3. 다음을 사용하여 .env 파일을 구성하세요.
   • UNRAID_API_URL : GraphQL URL(예: http://your-unraid-server-ip/graphql )
   • UNRAID_API_KEY : 생성한 API 키
4. http://your-unraid-server-ip/graphql 에서 GraphQL 샌드박스를 사용하여 API를 테스트하세요.

참고 : Unraid API는 인증을 위해 Bearer 토큰이 아닌 x-api-key 헤더를 사용합니다.

문제 해결

• CORS 오류가 발생하는 경우 클라이언트에 서버의 URL과 일치하는 올바른 Origin 헤더가 포함되어 있는지 확인하세요.
• 실행하려는 쿼리에 필요한 역할과 권한이 API 키에 있는지 확인하세요.
• GraphQL 샌드박스가 활성화되어 있고 접근 가능한지 확인하세요.

용법

MCP 서버 실행

AI 어시스턴트와 통합하려면 stdio 모드에서 서버를 실행하세요.

stdio 모드는 다음과 같은 경우에 유용합니다.

• MCP 프로토콜을 지원하는 AI 어시스턴트와의 직접 통합
• Anthropic Python SDK로 테스트하기
• 커서에서 Claude와의 통합

stdio 모드로 실행될 때 서버는 MCP 프로토콜 형식에 따라 표준 입력에서 데이터를 읽고 표준 출력에 데이터를 씁니다. 이를 통해 HTTP 전송 없이 AI 어시스턴트와 직접 통신할 수 있습니다.

서버 아키텍처

서버는 FastMCP 프레임워크를 사용하여 구축되었으며 다음으로 구성됩니다.

1. Unraid API 클라이언트 ( unraid_client.py ):
   • Unraid 서버와의 GraphQL 통신을 처리합니다.
   • 인증 및 오류 처리를 관리합니다.
   • 일관된 오류 보고를 제공합니다
2. MCP 서버 ( server.py ):
   • MCP 사양에 따라 리소스와 도구를 정의합니다.
   • AI 어시스턴트에 Unraid 기능을 공개합니다.
   • 요청 검증 및 오류 진단을 처리합니다.

사용 가능한 리소스

사용 가능한 도구

시스템 관리

어레이 관리

도커 관리

VM 관리

알림 관리

주식 관리

디스크 관리

사용자 관리

API 키 관리

Claude와의 통합

Claude API 또는 stdio 모드를 지원하는 다른 AI 어시스턴트와 함께 MCP 서버를 사용하려면:

1. 구성 파일을 만듭니다(예: unraid_mcp_config.json ):
   { "mcpServers": { "unraid": { "command": "/path/to/python", "args": ["/path/to/unraid-mcp/run_server.py"], "env": { "UNRAID_API_URL": "http://your-unraid-server:port/graphql", "UNRAID_API_KEY": "your-api-key", "LOG_LEVEL": "INFO", "CLAUDE_MCP_SERVER": "true" }, "disabled": false, "autoApprove": [] } } }

참고 : Windows 사용자의 경우 경로에 백슬래시를 두 개 사용해야 합니다(예: C:\\Users\\username\\unraid-mcp\\run_server.py ).

예제 쿼리

• "내 Unraid 서버의 현재 CPU 사용량은 얼마입니까?"
• "내 모든 Docker 컨테이너 나열"
• "내 Plex 컨테이너에 대해 알려주세요"(container_details 리소스 사용)
• "Plex 컨테이너 시작"
• "내 배열의 상태는 어떻습니까?"
• "내 Unraid 서버에 얼마나 많은 여유 공간이 있나요?"
• "내 Windows VM에 대한 세부 정보를 보여주세요"(vm_details 리소스 사용)
• "어떤 플러그인을 설치했나요?"

문제 해결

자세한 오류 정보는 로그 파일( unraid_mcp.log )에서 확인하세요.

일반적인 문제:

• .env 파일에 잘못된 API URL 또는 키가 있습니다.
• Unraid 서버에 대한 네트워크 연결 문제
• API 키에 대한 권한이 부족합니다.
• Unraid 서버에서 개발자 모드가 활성화되지 않았습니다.
• API 키에 필요한 역할이 없습니다.

기여하다

기여를 환영합니다! 풀 리퀘스트를 제출해 주세요.

특허

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.

참고문헌

• 모델 컨텍스트 프로토콜
• MCP 파이썬 SDK
• Unraid API 문서