Unraid MCP

로컬 Model Context Protocol 서버로서 AI 클라이언트가 Unraid의 공식 GraphQL API를 통해 Unraid 서버를 검사하고 관리할 수 있게 합니다.

AI 지원 개발 고지: 이 프로젝트는 AI 코딩 에이전트의 상당한 도움을 받아 설계, 연구, 구현, 문서화, 테스트되었습니다. 공식 Unraid 프로젝트가 아닙니다. Unraid 서버에 대한 접근 권한을 부여하기 전에, 특히 변형 도구를 활성화하기 전에 소스, 권한, 보안 설정을 직접 검토하십시오.

MCP는 기본적으로 읽기 전용입니다. 변형 도구는 환경 변수를 통해 명시적으로 활성화하기 전까지 완전히 제외되며, 영구적/고위험 작업에는 두 번째 게이트가 사용됩니다.

요구 사항

• Node.js 22 이상

• pnpm 11

• API가 OS에 내장된 Unraid 7.2 이상

• Unraid API 키

Unraid 7.0-7.1은 Unraid Connect 플러그인을 통해 API v4를 노출할 수 있지만, Unraid는 이 조합을 제한적 지원으로 문서화합니다. 이 프로젝트의 GraphQL 문서는 Unraid 7.3.2에 번들된 API v4.35.1을 대상으로 합니다. 이전 API 릴리스는 메트릭, 로그, UPS 필드와 같은 최신 쿼리를 거부할 수 있습니다.

Related MCP server: GraphQL MCP Toolkit

Unraid 설정

1. Unraid WebGUI에서 Settings > Management Access > API Keys를 엽니다.

2. 이 MCP용 키를 생성합니다.

3. 읽기 전용 액세스를 위해 VIEWER 역할로 시작합니다.

4. 생성된 키를 UNRAID_API_KEY에 저장합니다. 소스 제어나 명령줄 인수에 절대 넣지 마십시오.

해당하는 Unraid 터미널 명령은 다음과 같습니다:

unraid-api apikey --create --name "Unraid MCP read only" --roles VIEWER --json

변형 액세스의 경우 ADMIN보다 세분화된 권한을 선호하십시오. 활성화하려는 도구에서 사용하는 리소스만 선택하십시오. 예: ARRAY, DOCKER, VMS, NOTIFICATIONS와 READ_ANY, UPDATE_ANY, 그리고 필요한 경우에만 DELETE_ANY.

GraphQL Sandbox는 이 MCP에 필요하지 않습니다. 개발 외에는 비활성화된 상태로 두십시오. 활성화하면 스키마 인트로스펙션도 활성화되기 때문입니다.

설치

pnpm install --frozen-lockfile
pnpm build

의존성은 정확한 버전으로 고정되며 설치 시 lockfile이 고정됩니다. pnpm은 또한 7일 이내에 게시된 릴리스(게시 시간이 누락된 패키지 포함)를 거부하고, 패키지/스토어 무결성을 검증하며, 선언되지 않은 라이프사이클 스크립트를 차단하고, 패키지 신뢰 등급 하향을 거부합니다. undici-types@6.21.0에 대한 버전별 신뢰 예외는 고정된 @types/node에 필요하며, 기간, 무결성, lockfile 검사는 여전히 적용됩니다. 검토 후 격리 기간을 거쳐 의도적으로 의존성을 업데이트하려면 정확한 버전을 사용하고 lockfile 변경을 명시적으로 허용하십시오:

pnpm update --exact --no-frozen-lockfile package-name@x.y.z
pnpm verify
pnpm audit

업데이트를 수락하기 전에 package.json과 pnpm-lock.yaml을 모두 검토하십시오. 이러한 제어 기능을 유지하지 않고 자동화된 의존성 업데이트 작업을 추가하지 마십시오.

MCP를 시작하는 환경에서 구성을 설정하십시오:

export UNRAID_URL="https://tower.local"
export UNRAID_API_KEY="your-api-key"
node /absolute/path/to/unraid-mcp/dist/index.js

UNRAID_URL은 WebGUI origin(이 경우 /graphql이 추가됨) 또는 정확한 GraphQL 엔드포인트일 수 있습니다. 최종 HTTPS URL을 직접 구성하십시오. 리디렉션은 거부되므로 API 키가 다른 origin으로 전달될 수 없습니다.

컨테이너 이미지

버전이 지정된 릴리스 이미지는 Docker Hub에 linux/amd64 및 linux/arm64용으로 게시됩니다. 변경 가능한 latest 태그에 의존하지 말고 배포에는 버전이나 이미지 다이제스트를 고정하십시오:

docker pull lemanjo/unraid-mcp:0.1.1

최종 이미지는 다이제스트로 고정된 Distroless Node.js 런타임을 사용합니다. 셸, 패키지 관리자, npm 또는 기타 빌드 도구 없이 숫자형 비루트 사용자로 실행됩니다. 컨테이너 빌드는 Trivy로 스캔되며, 수정 가능한 치명적 또는 높은 취약점이 있으면 레지스트리 로그인 전에 실패합니다.

Unraid 서버 또는 다른 Docker 호스트에서 프로덕션 이미지를 빌드하십시오:

docker build --tag unraid-mcp:0.1.1 .

로컬 stdio 컨테이너

기본 전송 방식은 stdio입니다. --env NAME은 이미지나 명령 인수에 비밀을 넣지 않고 실행 환경의 값을 전달합니다:

export UNRAID_URL="https://tower.local"
export UNRAID_API_KEY="your-api-key"

docker run --rm -i \
  --env UNRAID_URL \
  --env UNRAID_API_KEY \
  unraid-mcp:0.1.1

선택적 구성도 같은 방식으로 전달하십시오(예: --env UNRAID_ALLOW_MUTATIONS). 사용자 지정 CA 파일은 읽기 전용으로 마운트하고 컨테이너 경로를 구성하십시오:

docker run --rm -i \
  --env UNRAID_URL \
  --env UNRAID_API_KEY \
  --env UNRAID_CA_CERT_PATH=/certs/unraid-ca.pem \
  --volume /host/path/unraid-ca.pem:/certs/unraid-ca.pem:ro \
  unraid-mcp:0.1.1

stdio 모드에서 이미지는 포트를 수신하지 않습니다. AI 호스트는 docker run --rm -i로 이미지를 시작하고 수명을 관리합니다.

상시 실행 원격 HTTP 컨테이너

컨테이너가 AI 클라이언트와 다른 머신에서 실행되는 경우 인증된 Streamable HTTP를 사용하십시오. 신뢰할 수 있는 머신에서 영구 MCP 토큰을 생성하십시오:

export MCP_AUTH_TOKEN="$(openssl rand -hex 32)"
export UNRAID_URL="https://tower.local"
export UNRAID_API_KEY="your-unraid-api-key"
export MCP_ALLOWED_HOSTS="mcp-server.example,192.168.1.20"

원격 컨테이너를 시작하십시오:

docker network create unraid-mcp-backend

docker run -d \
  --name unraid-mcp \
  --restart unless-stopped \
  --network unraid-mcp-backend \
  --env MCP_TRANSPORT=http \
  --env MCP_HOST=0.0.0.0 \
  --env MCP_PORT=3000 \
  --env MCP_ALLOWED_HOSTS \
  --env MCP_AUTH_TOKEN \
  --env UNRAID_URL \
  --env UNRAID_API_KEY \
  unraid-mcp:0.1.1

MCP_ALLOWED_HOSTS는 IPv4 또는 IPv6 와일드카드 주소를 바인딩할 때 필수입니다. 클라이언트나 리버스 프록시가 HTTP Host 헤더에 넣을 모든 호스트 이름 또는 IP 주소를 나열하십시오. 항목에는 포트가 포함되지 않으며 IPv6 항목은 대괄호를 사용합니다. Localhost 값은 상태 점검을 위해 항상 포함됩니다.

MCP_AUTH_TOKEN을 생략하면 서버가 암호학적으로 무작위한 256비트 토큰을 생성하여 시작 중에 한 번 출력합니다:

docker logs unraid-mcp

Generated MCP auth token:을 찾으십시오. 해당 로그를 읽을 수 있는 사람은 MCP에 접근할 수 있으며, 변수가 설정되지 않은 상태로 프로세스가 재시작될 때마다 새 토큰이 생성됩니다. 안정적인 프로덕션 배포를 위해 MCP_AUTH_TOKEN을 명시적으로 설정하십시오. MCP 토큰은 UNRAID_API_KEY와 별개입니다. 원격 AI 클라이언트는 MCP 토큰만 필요합니다.

HTTP 리스너는 의도적으로 일반 HTTP입니다. 예제는 포트를 게시하지 않습니다. Caddy, Nginx 또는 Traefik 컨테이너를 unraid-mcp-backend에 연결하고 http://unraid-mcp:3000으로 프록시하십시오. 호스트에 설치된 프록시의 경우 Docker 28 이상은 127.0.0.1:3000:3000을 게시할 수 있습니다. 일부 Unraid 릴리스를 포함한 이전 Docker 버전은 localhost에 게시된 포트를 동일한 레이어-2 네트워크에 노출할 수 있으므로, 대신 프라이빗 네트워크나 명시적 방화벽 규칙을 사용하십시오. 포트 3000을 인터넷에 직접 노출하지 마십시오. 컨테이너 상태 점검은 GET /health를 호출하며, MCP 트래픽은 /mcp를 사용합니다.

내장 인증 스로틀은 직접적인 TCP 피어를 식별합니다. 리버스 프록시 뒤에서는 프록시에서도 인증 속도 제한을 구성하십시오. 모든 프록시 클라이언트가 하나의 피어 주소를 공유할 수 있기 때문입니다. 신뢰할 수 없는 Host 값을 전달하지 마십시오. 외부 호스트 이름을 유지하고 MCP_ALLOWED_HOSTS에 포함하거나, 고정된 허용 목록 호스트 이름으로 다시 쓰십시오.

로컬 Docker 클라이언트 구성

Docker 데몬을 통해 이미지를 시작하는 OpenCode 구성은 다음과 같습니다:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "unraid": {
      "type": "local",
      "command": [
        "docker",
        "run",
        "--rm",
        "-i",
        "--env",
        "UNRAID_URL",
        "--env",
        "UNRAID_API_KEY",
        "unraid-mcp:0.1.1"
      ],
      "enabled": true,
      "environment": {
        "UNRAID_URL": "{env:UNRAID_URL}",
        "UNRAID_API_KEY": "{env:UNRAID_API_KEY}"
      }
    }
  }
}

AI 호스트가 사용하는 Docker 데몬은 이미지에 접근할 수 있어야 합니다. 구성을 변경한 후 OpenCode를 다시 시작하십시오.

구성

UNRAID_CA_CERT 또는 UNRAID_CA_CERT_PATH 중 하나만 사용하십시오. 둘 다 사용하지 마십시오. Unraid의 인증서나 로컬 CA를 신뢰하는 것을 선호하십시오. UNRAID_TLS_SKIP_VERIFY=true는 명시적인 최후 수단이며 경고를 출력합니다. 다른 Node.js 연결의 TLS 동작을 전역적으로 변경하지는 않습니다.

일반 HTTP는 격리된 레거시 네트워크에서 지원되지만, API 키와 모든 서버 데이터가 암호화 없이 전송되므로 경고를 출력합니다.

AI 클라이언트 설정

OpenCode

OpenCode를 시작하기 전에 환경 변수를 내보낸 다음 이 로컬 MCP를 opencode.json에 추가하십시오:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "unraid": {
      "type": "local",
      "command": ["node", "/absolute/path/to/unraid-mcp/dist/index.js"],
      "enabled": true,
      "environment": {
        "UNRAID_URL": "{env:UNRAID_URL}",
        "UNRAID_API_KEY": "{env:UNRAID_API_KEY}",
        "UNRAID_CA_CERT_PATH": "{env:UNRAID_CA_CERT_PATH}",
        "UNRAID_ALLOW_MUTATIONS": "{env:UNRAID_ALLOW_MUTATIONS}",
        "UNRAID_ALLOW_DESTRUCTIVE_MUTATIONS": "{env:UNRAID_ALLOW_DESTRUCTIVE_MUTATIONS}"
      }
    }
  }
}

설정되지 않은 선택적 환경 항목은 제거하십시오. 구성을 변경한 후 OpenCode를 다시 시작하십시오.

상시 실행 HTTP 컨테이너에 연결하려면 OpenCode 머신에서 MCP 토큰을 내보내고 원격 서버를 구성하십시오:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "unraid": {
      "type": "remote",
      "url": "https://mcp-server.example/mcp",
      "enabled": true,
      "oauth": false,
      "headers": {
        "Authorization": "Bearer {env:MCP_AUTH_TOKEN}"
      }
    }
  }
}

Unraid GraphQL URL이 아닌 HTTPS 리버스 프록시 URL을 사용하십시오. OpenCode는 MCP_AUTH_TOKEN을 MCP로 보내며, MCP 컨테이너만 UNRAID_API_KEY를 Unraid로 보냅니다.

Claude Code

Claude Code를 시작하기 전에 UNRAID_URL과 UNRAID_API_KEY를 내보내십시오. 프로젝트 범위로 사용하려면 Claude Code를 사용하는 프로젝트에 .mcp.json을 만드십시오:

{
  "mcpServers": {
    "unraid": {
      "command": "node",
      "args": ["/absolute/path/to/unraid-mcp/dist/index.js"],
      "env": {
        "UNRAID_URL": "${UNRAID_URL}",
        "UNRAID_API_KEY": "${UNRAID_API_KEY}"
      }
    }
  }
}

Claude Code는 ${VAR} 참조를 환경에서 확장합니다. 따라서 API 키를 저장하지 않고 구성을 공유할 수 있습니다. 선택적 변수는 설정된 경우에만 env에 추가하십시오(예: "UNRAID_ALLOW_MUTATIONS": "${UNRAID_ALLOW_MUTATIONS}").

대신 컨테이너 이미지를 시작하려면 다음을 사용하십시오:

{
  "mcpServers": {
    "unraid": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--env",
        "UNRAID_URL",
        "--env",
        "UNRAID_API_KEY",
        "unraid-mcp:0.1.1"
      ],
      "env": {
        "UNRAID_URL": "${UNRAID_URL}",
        "UNRAID_API_KEY": "${UNRAID_API_KEY}"
      }
    }
  }
}

claude mcp list를 실행하여 서버를 확인한 다음 Claude Code 내에서 /mcp를 사용하여 상태와 도구를 검사하십시오. Claude Code는 프로젝트 범위의 .mcp.json 서버를 사용하기 전에 승인을 요청합니다. ~/.claude.json에 비공개 프로젝트 간 구성을 선호하는 경우 Claude Code의 MCP 명령에 --scope user를 사용하십시오.

상시 실행 HTTP 컨테이너의 경우 대신 이 .mcp.json 항목을 사용하십시오:

{
  "mcpServers": {
    "unraid": {
      "type": "http",
      "url": "https://mcp-server.example/mcp",
      "headers": {
        "Authorization": "Bearer ${MCP_AUTH_TOKEN}"
      }
    }
  }
}

Claude Code를 시작하기 전에 MCP_AUTH_TOKEN을 내보내십시오. ${MCP_AUTH_TOKEN} 참조는 프로젝트 구성에 값을 저장하지 않고 확장됩니다.

Codex CLI 및 IDE

Codex CLI, Codex IDE 확장, ChatGPT 데스크톱 앱은 MCP 구성을 공유합니다. 필요한 변수를 내보낸 다음 이 항목을 ~/.codex/config.toml 또는 신뢰할 수 있는 프로젝트의 .codex/config.toml에 추가하십시오:

[mcp_servers.unraid]
command = "node"
args = ["/absolute/path/to/unraid-mcp/dist/index.js"]
env_vars = ["UNRAID_URL", "UNRAID_API_KEY"]
startup_timeout_sec = 10
tool_timeout_sec = 120
default_tools_approval_mode = "writes"

env_vars는 Codex 환경의 값을 config.toml에 기록하지 않고 전달합니다. UNRAID_CA_CERT_PATH 또는 UNRAID_ALLOW_MUTATIONS와 같이 활성화된 선택적 설정이 있으면 해당 목록에 추가하십시오.

대신 컨테이너 이미지를 시작하려면 다음을 사용하십시오:

[mcp_servers.unraid]
command = "docker"
args = [
  "run",
  "--rm",
  "-i",
  "--env",
  "UNRAID_URL",
  "--env",
  "UNRAID_API_KEY",
  "unraid-mcp:0.1.1",
]
env_vars = ["UNRAID_URL", "UNRAID_API_KEY"]
startup_timeout_sec = 10
tool_timeout_sec = 120
default_tools_approval_mode = "writes"

writes 승인 모드는 읽기 전용으로 표시되지 않은 도구에 대해 프롬프트를 표시합니다. codex mcp list를 실행하여 서버를 확인하고, Codex TUI에서 /mcp를 사용하여 연결된 도구를 검사하세요. 공유 구성을 편집한 후 IDE 확장 프로그램 또는 ChatGPT 데스크톱 앱을 다시 시작하세요.

항상 켜져 있는 HTTP 컨테이너의 경우 다음 항목을 대신 사용하세요:

[mcp_servers.unraid]
url = "https://mcp-server.example/mcp"
bearer_token_env_var = "MCP_AUTH_TOKEN"
startup_timeout_sec = 10
tool_timeout_sec = 120
default_tools_approval_mode = "writes"

Codex는 로컬 환경에서 bearer 토큰을 읽으며 config.toml에 값을 저장하지 않습니다.

Claude Desktop 및 기타 stdio 호스트

호스트가 다음을 실행하도록 구성하세요:

node /absolute/path/to/unraid-mcp/dist/index.js

호스트 프로세스가 OS, 서비스 관리자 또는 시크릿 관리자로부터 필요한 환경 변수를 상속하도록 하세요. API 키를 args 배열에 넣지 마세요. 호스트가 서버별 환경 값을 지원하지만 시크릿 참조를 지원하지 않는 경우, 해당 값이 호스트의 구성 파일에 저장된다는 점을 이해하세요.

MCP Inspector

변수를 내보낸 상태에서 도구를 대화형으로 검사하고 호출하세요:

pnpm dlx @modelcontextprotocol/inspector node dist/index.js

Inspector는 의도적으로 프로젝트 종속성이 아닙니다. 환경에 대해 승인된 버전을 호출하세요.

도구

다음 읽기 도구는 항상 등록됩니다:

UNRAID_ALLOW_MUTATIONS=true는 다음을 추가합니다:

UNRAID_ALLOW_DESTRUCTIVE_MUTATIONS=true는 추가로 다음을 추가합니다:

또한 unraid_control_parity_check가 correct=true로 시작할 수 있게 합니다.

MCP 주석은 클라이언트에 대한 힌트일 뿐이며 접근 제어가 아닙니다. 환경 게이트와 Unraid API 키 자체의 권한이 실제 제어 수단입니다.

API 제한 사항

현재 공식 스키마는 모든 WebGUI 작업을 제공하지 않습니다. 특히:

• 공유는 읽기 전용입니다. 공유 생성/편집은 사용할 수 없습니다.

• Docker 컨테이너는 제어, 업데이트 및 제거가 가능하지만 생성 또는 편집은 불가능합니다.

• VM은 제어가 가능하지만 생성, 편집, 복제, 스냅샷 또는 삭제는 불가능합니다.

• 호스트 종료/재부팅 변경 작업은 게시되지 않습니다.

• 전체 SMART 보고서 및 SMART 자체 테스트 제어는 게시되지 않습니다.

• Docker restart는 API v4.35.1 이후에 추가되었으며 이 호환성 대상에서는 의도적으로 사용되지 않습니다.

• 패리티 변경 응답 유형은 Unraid에서 작업 진행 중으로 표시됩니다.

공식 소스 참조 및 호환성 세부 정보는 docs/api-capabilities.md를 참조하세요.

개발

pnpm typecheck
pnpm test
pnpm build
# Or run all three:
pnpm verify

테스트는 로컬 모의 HTTP 서버와 인메모리 및 Streamable HTTP MCP 클라이언트를 사용합니다. Docker 또는 실제 Unraid 서버가 필요하지 않습니다.

컨테이너 릴리스

GitHub Actions는 레지스트리 자격 증명 없이 pull request 및 main 변경 사항에 대해 컨테이너를 빌드하고 취약점을 스캔합니다. 게시는 v0.1.1과 같은 시맨틱 버전의 GitHub Release가 게시된 경우에만 발생합니다. 릴리스 워크플로는 보호된 dockerhub 환경의 DOCKERHUB_TOKEN에 접근하기 전에 빌드된 이미지를 스캔한 다음 버전, 커밋 및 (안정 릴리스의 경우) latest 태그를 SBOM 및 출처 증명과 함께 게시합니다.

보안 참고 사항

• Stdio가 기본값으로 유지되며 수신 네트워크 포트를 열지 않습니다.

• HTTP 모드에는 bearer 인증이 필요합니다. 누락된 토큰은 256비트 암호화 난수로 생성되며 의도적으로 시작 로그에 기록됩니다.

• 생성된 토큰은 운영상의 시크릿입니다. 로그 접근을 제한하고 안정적인 배포를 위해 MCP_AUTH_TOKEN을 구성하세요.

• HTTP 모드는 Host 및 Origin 헤더를 검증하고, 실패한 인증을 속도 제한하며, 요청 본문을 제한하고, 기본적으로 루프백 바인드를 사용합니다.

• 내장 HTTP 리스너는 TLS를 제공하지 않습니다. HTTPS 리버스 프록시를 사용하고 인터넷에 직접 노출하지 마세요.

• MCP JSON-RPC용으로 예약된 stdout에는 애플리케이션 로그를 절대 작성하지 않습니다.

• 모델로부터 임의의 GraphQL 문서를 수락하지 않습니다.

• 리디렉션을 따르지 않으며 응답 크기, 로그 줄 수 및 요청 기간을 제한합니다.

• 클라이언트 취소는 로컬 HTTP 요청을 중단합니다. Unraid가 이미 수락한 변경 작업은 롤백할 수 없습니다.

• GraphQL 오류에 구성된 API 키가 포함된 경우 오류가 편집됩니다.

• 디스크 일련 번호, 로그, 알림, 네트워크 주소 및 기타 서버 데이터는 연결된 AI 클라이언트에 표시됩니다. 해당 클라이언트의 데이터 처리 정책을 검토하세요.

공식 참조

• Unraid API 개요

• Unraid API 사용 방법

• 프로그래밍 방식 API 키 관리

• Unraid API 로드맵 및 버전 지원

• API v4.35.1 생성 GraphQL 스키마

• Unraid 연결 보안 지침

• MCP TypeScript SDK stdio 지침

• MCP TypeScript SDK Streamable HTTP 지침

• Claude Code MCP 구성

• Codex MCP 구성

라이선스

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여됩니다.