arr-mcp

작은 Model Context Protocol 서버로, *arr 미디어 스택(Sonarr, Radarr, Prowlarr, Jellyseerr, Bazarr)을 깔끔하고 타입이 지정된 도구 뒤에 배치합니다. Claude와 같은 MCP 클라이언트는 각 앱의 REST API를 통해 해당 도구를 직접 호출합니다 — 브라우저 없이, 화면 스크래핑 없이, LAN으로 VPN 없이.

서버는 API 키를 자체적으로 보유하며, 클라이언트는 이를 볼 수 없습니다. .104 도커 호스트에서 실행되며, 인증된 Cloudflare Tunnel을 통해 클라우드에서 접근할 수 있으므로, 집에 있든 휴대폰으로 Claude를 사용하든 작동합니다.

왜 이게 필요한가

Claude가 이전에 미디어 스택에서 수행한 모든 작업은 Mac의 브라우저 확장 프로그램을 통해 이루어졌습니다 — 이는 연결 ID 변경("어떤 브라우저?"), 세션/2FA 마찰, VPN + 원격 제어 절차를 초래했습니다. 이 서버는 브라우저와 Mac을 루프에서 완전히 제거하고, UI 스크래핑을 빠르고 구조화된 API 호출로 대체합니다.

Related MCP server: mcp-arr-suite

도구

* = 쓰기 작업(검색을 트리거하거나 시리즈의 블록리스트를 지웁니다). 그 외 모든 것은 읽기 전용입니다. 의도적으로 삭제/제거 또는 구성 변경 도구가 없습니다 — 이는 폭발 반경을 작게 유지합니다. 필요에 따라 나중에 더 추가하세요.

설정

cp config.example.env .env
# edit .env: real API keys (Settings > General > Security > API Key in each app)
# and a strong MCP_AUTH_TOKEN:  python3 -c "import secrets; print(secrets.token_urlsafe(48))"

docker compose up -d --build

빠른 로컬 확인(누락된 MCP 세션에 대한 400/406을 반환해야 합니다 — 이는 서버가 실행 중이고 토큰이 수락되었음을 의미합니다. 401은 토큰이 잘못되었음을 의미합니다):

curl -s -o /dev/null -w "%{http_code}\n" \
  -H "Authorization: Bearer <your MCP_AUTH_TOKEN>" \
  http://localhost:8787/mcp

Docker 없이 실행(개발용)

pip install -r requirements.txt
set -a; source .env; set +a
python server.py

Claude에 노출하기

MCP 엔드포인트는 https://<your-hostname>/mcp입니다.

1. 터널링. docker-compose.yml에서 cloudflared 서비스를 주석 해제하고 자체 터널을 제공하거나, 기존 Jellyfin 터널에 http://arr-mcp:8787(또는 호스트에서 http://localhost:8787)을 가리키는 호스트 이름을 추가하세요. 호스트 이름 앞에 Cloudflare Access를 배치하거나, 베어러 토큰에 의존하세요 — 이상적으로는 둘 다.

2. Claude에 사용자 지정 커넥터로 추가. 설정 → 사용자 지정 → 커넥터 → 사용자 지정 커넥터 추가 → URL https://<your-hostname>/mcp. 베어러 토큰을 Authorization: Bearer <token> 헤더로 제공하세요. 그러면 Claude가 위의 도구를 나열합니다.

보안 참고 사항

• 베어러 토큰(MCP_AUTH_TOKEN)은 엔드포인트가 인터넷에서 도달 가능해지기 전에 필수입니다. 비어 있으면 서버는 경고를 출력하고 인증 없이 서비스를 제공합니다 — localhost에 바인딩된 경우에만 허용됩니다.

• 컨테이너는 기본적으로 127.0.0.1:8787에 바인딩되므로 선택한 터널을 통해서만 노출됩니다.

• API 키는 .env(git-ignored, docker-ignored)에만 존재합니다. 유출되면 각 앱에서 회전하세요.

• 범위는 의도적으로 읽기 중심입니다. 파괴적인 도구(시리즈 삭제, 큐에서 제거, 설정 편집)를 추가하기 전에 인터넷에 도달 가능한 엔드포인트에서 편의성이 위험을 감수할 가치가 있는지 결정하세요.

파일

• server.py — MCP 서버 및 모든 도구(streamable-HTTP 전송 + 베어러 인증)

• arr_client.py — 모든 서비스가 공유하는 얇은 비동기 REST 클라이언트

• config.py — 환경 변수에서 서비스별 클라이언트를 빌드(누락 = 비활성화)

• Dockerfile / docker-compose.yml — 컨테이너 + 선택적 터널

• config.example.env — .env로 복사