Navidrome MCP 서버

Navidrome용 MCP(Model Context Protocol) 서버입니다. Claude Desktop, Claude Code, Cursor 및 기타 MCP 클라이언트에서 라이브러리를 탐색하고, 재생 목록을 만들고, 새 음악을 발견하고, 컴퓨터 스피커로 오디오를 재생할 수 있습니다.

목차

• 기능

• 사용 가능한 도구

• 설치 및 설정

• 문제 해결

• 개발

• 라이선스

• 지원

Related MCP server: Spotify MCP Server

기능

🎵 음악 라이브러리

노래, 앨범, 아티스트, 장르, 태그를 탐색하고 검색할 수 있습니다. 필터는 검색어, 별표 상태, 연도 범위, 정렬 순서, 태그 값을 다루며 서로 결합할 수 있습니다: "90년대 별표한 재즈 앨범 전체를 연도순으로 정렬" 또는 "Soundtrack 태그가 붙은 5점짜리 모든 노래". 태그 분석 도구는 라이브러리에 무엇이 있는지 보여주므로 필터 값을 추측할 필요가 없습니다.

🔊 로컬 오디오 재생

MCP 서버를 실행하는 호스트에 mpv가 필요합니다(mpv 설치 참조).

브라우저나 Navidrome 웹 UI 없이 컴퓨터 스피커로 오디오가 재생됩니다. 검색과 재생을 한 번에: "별표한 앨범 5개를 무작위로 재생", "90년대에 별표한 모든 항목을 연도순으로 대기열에 추가", 또는 "재생 중인 목록에 무작위 록 노래 10개를 셔플로 추가". 앨범에는 세 가지 셔플 모드가 있습니다: 순서 유지, 앨범 순서 무작위화, 트랙 인터리브.

재생 중에도 대기열을 편집할 수 있습니다: 현재 노래를 중단하지 않고 순서를 바꾸거나 셔플할 수 있으며, 현재 트랙을 제거하면 다음 트랙으로 넘어갑니다. 저장된 Navidrome 라디오 방송국(Icecast, SHOUTcast)은 실시간 ICY 메타데이터와 함께 mpv로 스트리밍되므로 방송국에서 재생 중인 내용을 확인할 수 있습니다. 재생 기록은 Navidrome으로 스크로블되어 재생 횟수와 최근 활동이 동기화됩니다. mpv는 첫 사용 시 시작되며, 사용자별 소켓을 통해 MCP 클라이언트 재시작에도 유지됩니다(수명 규칙은 MPV Remote 설정 참조). Linux, macOS, Windows 11에서 작동합니다.

이 기능은 Raspberry Pi 또는 상시 켜진 머신에서 핸즈프리 음악 기기를 위한 음성 전송(Whisper STT + TTS)과 함께 작동합니다.

🎛️ MPV Remote(웹 UI)

mpv가 필요합니다(로컬 오디오 재생과 동일). 기본적으로 켜져 있으며 서버와 함께 시작됩니다.

http://localhost:8808의 웹 UI는 모든 브라우저에 로컬 재생 컨트롤을 제공합니다: 커버 아트가 있는 현재 재생 중, 재생/탐색 및 시크, 볼륨, 클릭하여 이동할 수 있는 실시간 업데이트되는 라이브 대기열. 내장 선택기를 사용하면 페이지에서 모든 재생 목록, 별표한 노래 또는 별표한 앨범을 시작할 수 있으므로 어시스턴트 없이 리모컨으로 작동합니다. Expose on LAN을 활성화하면 휴대폰이나 태블릿에서 재생을 제어할 수 있습니다. 오디오는 항상 서버를 실행하는 머신에서 출력됩니다. 설정, 수명, 보안 세부 사항은 MPV Remote 설정에 있습니다.

🎶 재생 목록

재생 목록을 만들고, 업데이트하고, 순서를 바꾸고, 삭제할 수 있습니다. 한 번의 작업으로 노래, 전체 앨범, 아티스트 음반 목록 또는 특정 디스크를 추가할 수 있습니다. 특정 노래가 포함된 재생 목록을 찾을 수 있습니다. 청취 데이터로 재생 목록을 만들 수 있습니다: "재생 횟수 5회 미만인 5점짜리 노래로 구성된 'Hidden Gems' 재생 목록" 또는 "상위 10명의 아티스트 각 앨범에서 최고 트랙 하나씩을 연대순으로".

🎼 음악 발견(Last.fm)

Last.fm API 키가 필요합니다(last.fm/api에서 무료), 설정 페이지에서 설정합니다.

유사한 아티스트와 트랙을 찾고, 전기와 인기 트랙을 가져오고, 글로벌 음악 차트를 탐색할 수 있습니다. 이를 라이브러리와 결합하여 누락된 앨범을 찾거나("상위 5명의 아티스트에서 누락된 앨범을 인기순으로 정렬"), 간과된 음악을 재발견하거나("내가 좋아하는 것과 유사하지만 소유하고도 재생하지 않는 트랙"), 소유한 음악으로 "Best Of" 재생 목록을 만들 수 있습니다.

🎤 동기화된 가사

설정 페이지에서 활성화합니다(LRCLIB 제공자 + 사용자 에이전트). API 키가 필요 없습니다.

LRCLIB 커뮤니티 데이터베이스에서 제목, 아티스트, 앨범, 길이로 매칭된 시간 동기화 가사(LRC 형식, 밀리초 타임스탬프)를 가져옵니다. 동기화된 버전이 없으면 일반 텍스트가 반환됩니다.

📻 인터넷 라디오

Navidrome 라디오 방송국을 관리하고 전 세계에서 새로운 방송국을 발견할 수 있습니다. 스트림 URL은 추가되기 전에 검증되며(MP3, AAC, OGG, FLAC 감지), SHOUTcast/Icecast 메타데이터가 추출됩니다. 대량 유지 관리가 가능합니다: "모든 방송국을 검증하고 고장난 것을 제거" 또는 "이 10개 URL을 테스트하고 작동하는 것만 추가".

글로벌 발견은 Radio Browser를 사용합니다(사용자 에이전트 필요, 설정 페이지에서 설정). 장르, 국가, 언어, 코덱, 비트레이트, 인기도 필터로 수천 개의 방송국을 다룹니다. 투표와 클릭이 등록되므로 사용량이 커뮤니티 순위에 반영됩니다.

📊 청취 분석

재생 횟수, 최근 활동, 최고 평점 및 최다 재생 목록, 라이브러리 전체의 태그 분포에 접근할 수 있습니다. 이를 사용하여 습관을 비교하고("올해 더 많이 vs 덜 재생하는 장르"), 잊혀진 즐겨찾기와 원히트 원더를 찾거나, 청취 패턴에서 무드 재생 목록을 만들 수 있습니다.

⭐ 평점 및 즐겨찾기

노래, 앨범, 아티스트에 별표를 추가하거나 제거할 수 있습니다. 0-5점 평점을 설정하고 별표 또는 최고 평점 항목을 나열할 수 있습니다. 웹 UI가 크로스 디바이스 동기화에 사용하는 저장된 Navidrome 대기열을 읽고 쓸 수 있습니다.

📚 다중 라이브러리 지원

모든 작업을 Navidrome 라이브러리의 하위 집합으로 필터링할 수 있습니다. 설정 페이지에서 기본값을 설정하거나(Default libraries, library.defaultLibraryIds) 런타임에 활성 라이브러리를 전환할 수 있습니다.

사용 가능한 도구

제목에 **requires ...**라고 표시된 도구 범주는 해당 구성이 있을 때만 등록됩니다.

핵심 시스템

라이브러리 관리

검색

재생 목록

평점 및 즐겨찾기

청취 기록 및 저장된 대기열

메타데이터 및 태그

Last.fm 발견(Last.fm API 키 필요)

가사(LRCLIB 제공자 필요, 설정 페이지에서 설정)

라디오 관리

글로벌 라디오 검색(Radio Browser 사용자 에이전트 필요)

로컬 재생(mpv 필요)

재생은 기본적으로 원본 파일을 스트리밍합니다(첫 실행 설정의 트랜스코드 형식 참조).

설치 및 설정

사전 요구 사항

• Node.js 20+ (다운로드)

• 실행 중인 Navidrome 서버

• MCP 호환 클라이언트 (Claude Desktop, Claude Code, Cursor 또는 로컬 stdio를 지원하는 다른 MCP 클라이언트)

• 선택 사항: mpv 로컬 오디오 재생용

빠른 설정

게시된 패키지 설치(실행 시 자동 업데이트):

npm install -g navidrome-mcp

패키지: npm의 navidrome-mcp.

개발 빌드의 경우:

git clone https://github.com/Blakeem/Navidrome-MCP.git
cd Navidrome-MCP
pnpm install
pnpm build

MCP 클라이언트 구성

MCP 클라이언트 구성은 클라이언트에 서버를 실행하는 방법만 알려줍니다. Navidrome 자격 증명과 모든 옵션은 브라우저 설정 페이지를 통해 편집되는 로컬 settings.json에 저장되므로 클라이언트 JSON이나 환경에 비밀이 포함되지 않습니다. 설정 페이지는 첫 실행 시 열립니다(첫 실행 설정 참조).

Claude Desktop의 경우 claude_desktop_config.json을 편집합니다(위치: Windows의 %APPDATA%/Claude/, macOS의 ~/Library/Application Support/Claude/, Linux의 ~/.config/Claude/). 다른 MCP 클라이언트도 동일한 JSON 형식을 사용합니다.

{
  "mcpServers": {
    "navidrome": {
      "command": "npx",
      "args": ["navidrome-mcp"]
    }
  }
}

수동 빌드의 경우 command/args를 다음으로 바꿉니다:

"command": "node",
"args": ["/absolute/path/to/Navidrome-MCP/dist/index.js"]

첫 실행 설정

구성 없이 처음 시작하면 설정 페이지가 브라우저에서 열립니다. MCP 서버를 실행했든 독립형 웹 플레이어(navidrome-web)를 실행했든 동일합니다. 브라우저를 열 수 없는 경우(예: SSH를 통한 경우) URL이 콘솔에 출력되며, 구성되지 않은 MCP 서버는 URL을 반환하는 open_settings 도구를 노출합니다. 언제든지 다음으로 설정 페이지를 엽니다:

npx navidrome-config

Navidrome URL, 사용자 이름, 비밀번호와 선택적 기능을 입력합니다. 그런 다음 연결 테스트와 저장을 클릭합니다. 이렇게 하면 로컬 settings.json이 생성됩니다(형식: settings.example.json). 설정은 시작 시 로드되며 핫 리로드되지 않으므로 실행한 것을 다시 시작하세요: MCP 클라이언트를 종료하고 다시 열거나 navidrome-web을 다시 실행하세요. 이전 env 설정에서 업그레이드하는 경우 양식이 이전 env/.env 값으로 미리 채워집니다. 확인하고 저장하세요.

헤드리스 머신 및 컨테이너: 설정 페이지는 루프백에만 바인딩되므로 브라우저가 없는 호스트(VPS, Docker 컨테이너)는 대신 환경 변수로 구성됩니다. settings.json이 없으면 서버는 NAVIDROME_URL, NAVIDROME_USERNAME, NAVIDROME_PASSWORD와 MCP_TRANSPORT, LASTFM_API_KEY 같은 선택적 변수로 실행됩니다. settings.json은 생성되면 항상 env보다 우선합니다.

필수: Navidrome URL, 사용자 이름, 비밀번호.

선택 사항(설정 페이지에서 설정):

• 기본 라이브러리: 기본으로 활성화할 쉼표로 구분된 라이브러리 ID. 비어 있으면 모두.

• Last.fm API 키: Last.fm 검색 활성화.

• Radio Browser 사용자 에이전트: 전 세계 방송국 검색 활성화.

• 가사 제공자(LRCLIB) + 사용자 에이전트: 가사 가져오기 활성화.

• mpv 경로: PATH에 없을 때 mpv 바이너리 위치. 비어 있으면 자동 감지.

• 트랜스코드 형식: 기본값은 raw로, 최상의 품질과 안정적인 탐색을 위해 원본 파일을 스트리밍합니다. 느리거나 데이터 제한이 있는 링크의 경우 코덱(예: mp3, opus)을 설정하세요. 비트레이트는 코덱이 설정된 경우에만 적용됩니다.

• 웹 UI (포트 / 호스트 / 노출 / 활성화 / 브라우저 자동 열기): MPV Remote 구성(MPV Remote 설정 참조). 기본값은 localhost:8808.

• 전송 (유형 / 호스트 / 포트): 서버가 MCP 프로토콜을 노출하는 방식. 기본값은 데스크톱 클라이언트가 사용하는 로컬 전송인 stdio. 서버를 네트워크 프로세스로 실행하려면 type을 http로 설정하세요(HTTP를 통한 실행 참조).

설정이 있으면 기능이 켜집니다.

mpv 설치(선택 사항)

mpv는 크로스 플랫폼 미디어 플레이어입니다. 서버는 시작 시 mpv를 감지하면 재생 도구를 등록합니다. mpv가 없어도 서버는 라이브러리와 저장된 Navidrome 큐를 관리하지만 오디오는 출력하지 않습니다.

macOS (Homebrew를 통해):

brew install mpv

Linux:

sudo apt install mpv       # Debian / Ubuntu / Mint / PopOS
sudo dnf install mpv       # Fedora / RHEL / CentOS Stream
sudo pacman -S mpv         # Arch / Manjaro
sudo zypper install mpv    # openSUSE

Windows:

winget install shinchiro.mpv   # winget is included on Windows 11
scoop install mpv
choco install mpv

전체 ID shinchiro.mpv를 사용하세요. 일반 winget install mpv는 비공식 Store 패키지와 선택하라는 메시지를 표시합니다. shinchiro 빌드는 mpv.io가 Windows용으로 링크하는 것입니다.

Windows PATH 참고. shinchiro.mpv 패키지는 C:\Program Files\MPV Player\에 설치되며 PATH에 자동으로 추가되지 않습니다. 다음 중 하나를 수행하세요:

• 해당 폴더를 PATH에 추가(시스템 속성 → 환경 변수 → Path → 새로 만들기)한 다음 새 터미널을 열거나,

• 설정 페이지(playback.mpvPath)에서 mpv 경로를 전체 mpv.exe 경로로 설정하세요(예: C:\Program Files\MPV Player\mpv.exe).

다른 설치 방법(scoop, choco, 수동 zip)은 다른 폴더를 사용합니다. 새 터미널에서 mpv --version이 실패하면 mpv.exe를 찾아 위 수정 사항 중 하나를 적용하세요.

mpv.io의 사전 빌드 바이너리도 작동합니다. mpv --version으로 확인하세요. 그런 다음 MCP 클라이언트를 다시 시작하여 서버가 mpv를 다시 감지하도록 하세요.

MPV Remote 설정

활성화 및 수명

패널은 기본적으로 켜져 있습니다. 서버는 이를 별도의 navidrome-web 프로세스로 시작하고 포트가 즉시 바인딩되므로 아무것도 재생되기 전에 페이지에 접근할 수 있습니다. mpv가 없는 호스트는 시작하지 않습니다. 플레이어 설정은 플레이어 내부의 기어 아이콘 뒤에 있으며, 기어 및 전원 버튼은 호스트 머신의 브라우저에만 표시됩니다.

AI 클라이언트를 닫아도 재생이 유지되는지 여부:

• 기본값(꺼짐): MCP 서버가 닫히거나 다시 시작되면 MCP로 실행된 플레이어와 mpv가 중지됩니다.

• MCP 서버가 닫힌 후에도 계속 재생 (설정 페이지 또는 기어 모달의 webui.persistAfterMcpExit): 플레이어가 계속 실행됩니다. 전원 버튼으로 중지하세요.

• 직접 실행 (아래 navidrome-web): 항상 독립적으로 실행됩니다. MCP 서버가 여기에 연결되며 종료하지 않습니다.

플레이어가 중지되면 mpv도 중지되며 백그라운드 유휴 시간 초과가 없습니다. 패널을 비활성화하려면 설정 페이지(webui.enabled)에서 동반 제어 패널 활성화를 선택 해제하세요.

독립 실행

MCP 클라이언트와 독립적으로 플레이어를 실행합니다:

navidrome-web                # after: npm install -g navidrome-mcp
# or, from a dev clone / manual build:
node dist/web/main.js

settings.json을 읽고 브라우저를 연 다음 전원 버튼으로 중지할 때까지 백그라운드에서 실행됩니다. MCP로 실행된 인스턴스와 공존합니다: 포트를 먼저 바인딩하는 프로세스가 소유하고 다른 프로세스가 연결됩니다. 로그는 구성 디렉터리의 navidrome-web.log에 기록됩니다.

아직 아무것도 구성되지 않은 경우, 실행하면 플레이어 대신 설정 페이지가 열립니다(최초 실행 설정 참조). 내용을 입력하고 저장하세요. 그런 다음 navidrome-web을 다시 실행하세요.

바탕화면 바로가기(권장)

플랫폼에 맞는 더블클릭 가능한 아이콘을 생성합니다. 터미널 창 없이 백그라운드에서 플레이어를 시작하고 브라우저를 엽니다. 이미 플레이어가 실행 중이라면 브라우저만 엽니다.

navidrome-web-shortcut       # after: npm install -g navidrome-mcp
# or, from a dev clone (see Development):
pnpm make:launcher

바로가기에는 node와 빌드된 플레이어의 절대 경로가 포함되므로 PATH에 아무것도 없어도 작동합니다. 다음 위치에 파일을 씁니다:

• Linux: 바탕화면과 앱 메뉴(~/.local/share/applications)에 Navidrome Player.desktop을 생성합니다. GNOME에서는 처음에 마우스 오른쪽 버튼 클릭 → Allow Launching을 선택하세요.

• macOS: 바탕화면에 Navidrome Player.app을 생성합니다(원하면 /Applications로 드래그).

• Windows: 바탕화면과 시작 메뉴에 Navidrome Player.vbs를 생성합니다. (OneDrive로 리디렉션된 바탕화면이면 해당 위치에 생성됩니다.)

프로젝트를 이동하거나 다시 빌드한 후에는 생성기를 다시 실행하여 경로를 갱신하세요.

구성

모든 설정은 선택 사항이며 설정 페이지의 Web UI 섹션에 있으며, 아래에는 settings.json 경로별로 정리되어 있습니다. 저장 후 클라이언트를 다시 시작하세요. 예외는 persistAfterMcpExit로, 기어 모달에서 즉시 적용됩니다.

휴대폰/태블릿 리모컨으로 사용하기

1. 설정 페이지에서 Expose on LAN을 활성화하고 저장하세요.

2. MCP 클라이언트를 다시 시작하세요(또는 navidrome-web을 다시 시작).

3. 플레이어는 바인딩 시점에 접근 가능한 LAN URL을 로그에 기록합니다(예: http://192.168.1.42:8808). 휴대폰 브라우저에서 해당 URL을 열고 북마크하세요.

보안 참고 사항

웹 UI에는 인증이 없습니다. 포트에 접근할 수 있는 사람은 누구나 일시 정지, 건너뛰기, 탐색, 볼륨 변경, 대기열 이동을 할 수 있습니다.

• webui.host=127.0.0.1(기본값)인 경우 호스트 머신에서만 접근할 수 있어 안전합니다.

• Expose on LAN(webui.expose=true)을 사용하면 LAN의 모든 기기에서 접근할 수 있습니다. 신뢰할 수 있는 홈 네트워크에서는 괜찮지만, 공개 인터넷에 노출하지 마세요. 속도 제한이 없으며 제어 API는 대기열 변경과 재생목록 시작을 허용합니다. 플레이어 설정과 전원 버튼은 루프백 전용으로 유지되며 원격 브라우저에는 숨겨지므로, LAN의 휴대폰은 재생을 제어할 수 있지만 설정을 변경하거나 플레이어를 종료할 수는 없습니다. 기본 설정 페이지는 절대 노출되지 않습니다. 노출된 경우 GET /healthz는 호스트 외부에서 404를 반환하여 버전 지문이 유출되는 것을 방지하므로, 플레이어의 상태는 호스트에서 확인하세요.

HTTP로 실행하기

기본적으로 서버는 stdio를 통해 MCP를 사용합니다. 클라이언트가 서버를 자식 프로세스로 실행하고 stdin/stdout으로 통신합니다. 이는 같은 머신의 데스크톱 클라이언트에서는 작동하지만 네트워크를 통해서는 접근할 수 없습니다.

전송 방식을 **http**로 설정하면 서버가 소켓에 바인딩하고 /mcp에서 MCP Streamable HTTP transport를 제공합니다. 그러면 supergateway나 mcp-proxy 브리지 없이 네트워크 MCP 클라이언트가 직접 연결하는 독립 프로세스로 실행됩니다.

settings.json에 transport 블록을 추가하세요. host는 기본적으로 127.0.0.1(루프백 전용)입니다. expose: true로 설정하면 모든 인터페이스(0.0.0.0)에 바인딩되어 원격 클라이언트가 접근할 수 있으며, 명시적인 host는 expose를 재정의합니다. authToken을 설정하면 bearer 인증이 필요합니다. 이는 포트가 루프백 너머에서 접근 가능할 때마다 권장되며, 설정 페이지에 Generate 버튼이 있습니다:

"transport": {
  "type": "http",
  "port": 3000,
  "expose": true,
  "authToken": "a-long-random-secret"
}

HTTP를 지원하는 MCP 클라이언트를 http://<host>:<port>/mcp에 연결하세요:

{
  "mcpServers": {
    "navidrome": {
      "type": "http",
      "url": "http://your-host:3000/mcp",
      "headers": { "Authorization": "Bearer a-long-random-secret" }
    }
  }
}

토큰이 설정되면 모든 /mcp 요청은 Authorization: Bearer <token>을携带해야 하며(일정 시간 비교), 그 외에는 401을 받습니다. 전송이 토큰 없이 비루프백 주소에 바인딩되면 서버는 시작을 거부하는 대신 시작 시 경고를 로그에 기록하므로, 방화벽이나 NetworkPolicy로 잠긴 배포도 계속 실행됩니다. GET /healthz는 절대 게이트되지 않습니다. 컨테이너 상태 확인을 위한 인증 없는 liveness 엔드포인트로, 200 {"status":"ok"}를 반환하며 Navidrome 호출을 하지 않습니다.

호스트 필터링(DNS 리바인딩 보호): 기본 바인딩(인증 토큰 없는 루프백)에서는 Host 헤더가 루프백 별칭이 아닌 요청이 거부되므로, 악성 웹 페이지가 브라우저를 통해 서버를 조종할 수 없습니다. authToken을 설정하거나 비루프백 주소에 바인딩하면 자동 필터가 꺼집니다. 원격 배포는 서버가 사전에 알 수 없는 이름으로 접근되며, bearer 토큰이 이미 리바인딩을 차단합니다(유인된 브라우저는 토큰을 첨부할 수 없음). 허용된 이름을 고정하려면 transport.allowedHosts를 설정하세요. 이는 존재할 때마다 적용됩니다. transport.allowedOrigins는 브라우저 클라이언트에만 설정하세요. Origin 헤더를 게이트합니다.

전송은 환경 변수로도 구성할 수 있습니다: MCP_TRANSPORT(stdio|http), MCP_HTTP_HOST, MCP_HTTP_PORT, MCP_HTTP_EXPOSE(true면 모든 인터페이스에 바인딩), MCP_HTTP_AUTH_TOKEN, MCP_HTTP_ALLOWED_HOSTS / MCP_HTTP_ALLOWED_ORIGINS(쉼표로 구분). 웹 UI에는 이에 대응하는 WEBUI_* 계열(WEBUI_ENABLED, WEBUI_PORT, WEBUI_HOST, WEBUI_EXPOSE, WEBUI_AUTO_OPEN_BROWSER, WEBUI_PERSIST_AFTER_MCP_EXIT)이 있습니다. 이들은 settings.json이 없을 때 적용되며, 최초 실행 시 설정 양식을 미리 채웁니다(최초 실행 설정 참조).

단일 계정, 공유 상태: 모든 HTTP 세션은 하나의 인증된 Navidrome 계정을 보유한 단일 프로세스가 제공하며, 활성 라이브러리 선택은 프로세스 전역입니다. set_active_libraries 호출은 연결된 모든 세션의 라이브러리 필터를 변경하며, get_user_details는 해당 공유 선택을 반영합니다.

보안: 서버는 인증된 Navidrome 세션을 보유하므로, 열린 포트는 자격 증명 없이 전체 라이브러리 제어를 의미합니다. localhost 너머로 포트를 노출하는 것은 옵트인(expose: true 또는 명시적 비루프백 host)입니다. 노출할 때는 인증 토큰을 설정하거나 방화벽, Kubernetes NetworkPolicy, TLS를 추가하는 리버스 프록시로 접근을 제한하세요. 원격 접근이 필요하지 않으면 기본 stdio 전송을 유지하세요.

오디오가 출력되는 위치. 전송은 MCP 프로토콜에 누가 접근할 수 있는지를 결정하며 오디오를 이동하지 않습니다. mpv는 서버 프로세스 옆에서 실행되므로 서버를 실행하는 머신이 소리를 냅니다. 컨테이너 외부의 머신에서 HTTP를 사용하면 원격 MCP 접근과 작동하는 재생이 가능합니다: 스피커에 연결된 머신에서 서버를 실행하고, 원격 클라이언트를 http://that-machine:3000/mcp에 연결하고, authToken을 설정하세요. 컨테이너는 라이브러리 도구(검색, 재생목록, 평점, 라디오 메타데이터, Last.fm, 가사) 전용의 항상 켜진 엔드포인트를 제공하며 오디오는 없습니다.

컨테이너의 경우 **Running in Docker**를 참조하세요: 이미지, 배포 형태, 마운트된 구성, 오디오 주의사항.

ChatGPT Desktop에 관한 참고 사항

ChatGPT의 MCP 지원(웹 및 데스크톱)은 호스팅된 HTTPS 엔드포인트가 필요하며 로컬 stdio 서버에서는 작동하지 않습니다. 이 서버는 HTTP를 통해 MCP를 제공할 수 있으므로(HTTP로 실행하기 참조), mcp-remote 같은 브리지 대신 TLS를 종료하는 리버스 프록시 뒤에서 호스팅할 수 있습니다. 자체 호스팅 음악 서버의 경우 Claude Desktop, Claude Code, Cursor 또는 stdio를 지원하는 다른 클라이언트를 사용하는 것이 더 간단합니다.

문제 해결

연결 문제

• Navidrome이 실행 중이고 접근 가능한지 확인하세요

• 설정 페이지의 Navidrome URL에 프로토콜(http:// 또는 https://)이 포함되어 있는지 확인하세요

• 저장 전에 설정 페이지의 Test connection 버튼을 사용하세요(또는 curl / 브라우저로 자격 증명 테스트)

macOS 관련

• macOS 문제 해결 가이드를 참조하세요. 일반적인 문제는 Node.js 경로를 찾지 못하는 것으로, 심볼릭 링크나 전체 경로로 해결됩니다.

구성

• 구성 파일에서 절대 경로를 사용하세요

• JSON 유효성 검사(후행 쉼표 없음)

• 변경 후 MCP 클라이언트를 다시 시작하세요

알려진 제한 사항

• mpv 없이는 오디오가 없습니다. 대신 Navidrome 웹 UI나 Subsonic 클라이언트를 사용하세요(mpv 설치 참조).

• 최근 재생 목록에는 타임스탬프가 없습니다. Navidrome은 재생 횟수와 완료 상태만 노출하며 마지막 재생 시점은 노출하지 않습니다.

• 저장된 대기열 ≠ 실시간 대기열. *_saved_queue 도구는 Navidrome의 서버 측 대기열(웹 UI 동기화)에서 작동합니다. *_play_queue 도구는 로컬 mpv 재생목록에서 작동합니다.

개발

git clone https://github.com/Blakeem/Navidrome-MCP.git
cd Navidrome-MCP
pnpm install
pnpm build
node dist/config-app/main.js   # opens the settings page; fill in + Save
# (writes settings.json to your OS config dir; see settings.example.json)

pnpm dev          # hot reload
pnpm test         # watch-mode tests
pnpm test:run     # one-shot tests
pnpm check:all    # lint + typecheck + dead-code
pnpm build        # production bundle

개발 빌드에서 독립형 웹 플레이어 테스트하기

이것은 릴리스가 npm에 도달하기 전에 플레이어를 시험해보는 소스 기반 경로입니다(게시된 패키지는 dev보다 뒤처질 수 있음). 둘 다 동일한 dist/에서 실행되므로 MCP 서버에도 적용됩니다.

# 1. Build (also bundles the web UI's static assets into dist/)
pnpm build

# 2. Configure if needed; writes settings.json to your OS config dir
node dist/config-app/main.js     # opens the settings page; fill in + Save

# 3. Run the standalone player directly
node dist/web/main.js            # serves http://127.0.0.1:8808 and opens your browser

해당 빌드로 더블클릭 가능한 아이콘을 만들려면(전역 설치 불필요):

pnpm make:launcher               # writes a shortcut to your Desktop + app menu

Windows 참고 사항(PowerShell):

• pnpm build 후 node dist\web\main.js를 사용하세요. 위와 동일하며 백슬래시를 사용합니다.

• pnpm make:launcher는 Navidrome Player.vbs를 바탕화면과 시작 메뉴에 씁니다. 콘솔 창 없이 node dist\web\main.js를 실행하고 이 체크아웃의 절대 경로를 포함하므로 폴더를 이동한 후 다시 실행하세요.

• 리디렉션된/OneDrive 바탕화면이 파일을 숨기면 시작 메뉴 복사본이 여전히 작동합니다(시작 → "Navidrome" 입력).

• 재생을 위해서는 mpv가 설치되어 있어야 합니다. PATH에 없으면 설정 페이지에서 playback.mpvPath를 설정하세요.

npm install -g navidrome-mcp 후에는 클론이나 빌드 없이 navidrome-web, navidrome-config, navidrome-web-shortcut으로 동일한 흐름이 실행됩니다.

MCP Inspector로 테스트:

pnpm build
npx @modelcontextprotocol/inspector node dist/index.js                  # web UI
npx @modelcontextprotocol/inspector --cli node dist/index.js \
  --method tools/call --tool-name search_all --tool-arg query="jazz"    # CLI

라이선스

• 코드: AGPL-3.0

• 문서: CC-BY-SA-4.0

지원

• GitHub Issues

• GitHub Discussions

Navidrome 커뮤니티를 위해 ❤️로 제작됨