Navidrome MCP Server

一个用于 Navidrome 的 MCP（模型上下文协议）服务器。Claude Desktop、Claude Code、Cursor 以及其他 MCP 客户端可以浏览你的音乐库、创建播放列表、发现新音乐，并通过你机器的扬声器播放音频。

目录

• 功能特性

• 可用工具

• 安装与设置

• 故障排查

• 开发

• 许可证

• 支持

Related MCP server: Spotify MCP Server

功能特性

🎵 音乐库

浏览和搜索歌曲、专辑、艺术家、流派和标签。筛选条件涵盖关键词、星标状态、年份范围、排序方式和标签值，并且可以组合使用："我所有 90 年代星标的爵士专辑，按年份排序" 或 "所有标记为 Soundtrack 且评分为 5 星的歌曲"。标签分析工具会展示你的音乐库中有哪些内容，这样你就不必猜测筛选值。

🔊 本地音频播放

需要运行 MCP 服务器的主机上安装 mpv（参见安装 mpv）。

音频通过你机器的扬声器播放，无需浏览器或 Navidrome 网页界面。一步完成搜索和播放："播放 5 张随机星标专辑"、"把我 90 年代星标的所有内容按年份排序加入队列" 或 "把 10 首随机摇滚歌曲添加到正在播放的内容中，随机播放"。专辑有三种随机模式：保持顺序、随机化专辑顺序或交错曲目。

播放过程中队列可编辑：无需中断当前歌曲即可重新排序或随机播放，移除当前曲目会自动播放下一首。已保存的 Navidrome 电台（Icecast、SHOUTcast）通过 mpv 流式播放，并带有实时 ICY 元数据，因此你可以看到电台正在播放什么。播放记录会回写到 Navidrome，使播放次数和最近活动保持同步。mpv 在首次使用时启动，可通过每用户 socket 在 MCP 客户端重启后继续存活（生命周期规则参见 MPV Remote 设置），并支持 Linux、macOS 和 Windows 11。

这可以与语音传输（Whisper STT + TTS）配合使用，在 Raspberry Pi 或常开机器上打造免提音乐设备。

🎛️ MPV Remote（网页界面）

需要 mpv（与本地音频播放相同）。默认开启，随服务器一起启动。

位于 http://localhost:8808 的网页界面为任何浏览器提供本地播放控制：正在播放及封面、传输和进度控制、音量，以及可点击跳转的实时队列，实时更新。内置选择器可从页面启动任何播放列表、你的星标歌曲或星标专辑，因此无需助手即可作为遥控器使用。启用 Expose on LAN 可从手机或平板控制播放。音频始终从运行服务器的那台机器输出。设置、生命周期和安全详情参见 MPV Remote 设置。

🎶 播放列表

创建、更新、重新排序和删除播放列表。一次操作即可添加歌曲、整张专辑、艺术家全部作品或特定碟片。查找哪些播放列表包含某首歌曲。根据收听数据构建播放列表："一个包含播放次数少于 5 次的 5 星歌曲的 'Hidden Gems' 播放列表" 或 "我前 10 位艺术家的每张专辑中各选一首热门曲目，按时间顺序排列"。

🎼 音乐发现（Last.fm）

需要 Last.fm API 密钥（在 last.fm/api 免费获取），在设置页面中配置。

查找相似艺术家和曲目、获取传记和热门曲目，以及浏览全球音乐排行榜。将其与你的音乐库结合，可以发现缺失的专辑（"我前 5 位艺术家中缺失的专辑，按热度排序"）、重新发现被忽视的音乐（"与我喜爱的歌曲相似、我拥有但从不播放的曲目"），或从你拥有的内容中构建"精选"播放列表。

🎤 同步歌词

在设置页面中启用（LRCLIB 提供方 + 用户代理）。无需 API 密钥。

从 LRCLIB 的社区数据库获取时间同步歌词（LRC 格式，毫秒级时间戳），按标题、艺术家、专辑和时长匹配。当没有同步版本时返回纯文本。

📻 网络电台

管理 Navidrome 电台并发现全球新电台。流媒体 URL 在添加前会经过验证（支持 MP3、AAC、OGG 和 FLAC 检测），并提取 SHOUTcast/Icecast 元数据。支持批量维护："验证我所有电台并移除失效的" 或 "测试这 10 个 URL 并添加可用的"。

全球发现使用 Radio Browser（需要用户代理，在设置页面中配置）。覆盖数千个电台，支持按流派、国家、语言、编解码器、比特率和热度筛选。投票和点击会被记录，因此你的使用会回馈社区排名。

📊 收听分析

访问播放次数、最近活动、最高评分和最常播放列表，以及音乐库中的标签分布。利用这些来比较收听习惯（"今年我播放更多 vs. 更少的流派"）、发现被遗忘的最爱和昙花一现的热门，或根据你的收听模式构建心情播放列表。

⭐ 评分与收藏

为歌曲、专辑和艺术家添加或取消星标。设置 0-5 星评分，并列出所有星标或最高评分的项目。读取和写入 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 服务器还是独立 Web 播放器（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 路径： 如果 mpv 二进制文件不在 PATH 中，则指定其位置。留空自动检测。

• 转码格式： 默认为 raw，即流式传输原始文件以获得最佳质量和可靠的定位。对于慢速或按流量计费的链接，可设置编解码器（例如 mp3、opus）。比特率仅在设置了编解码器时生效。

• Web UI（端口 / 主机 / 暴露 / 启用 / 自动打开浏览器）：配置 MPV Remote（参见 MPV Remote 设置）。默认为 localhost:8808。

• 传输方式（类型 / 主机 / 端口）：服务器如何暴露 MCP 协议。默认为 stdio，即桌面客户端使用的本地传输方式。将 type 设置为 http 可将服务器作为网络进程运行（参见通过 HTTP 运行）。

当存在相应设置时，功能即会开启。

安装 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 启动的播放器和 mpv 会在 MCP 服务器关闭或重启时停止。

• 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 上，首次使用时右键单击 → 允许启动。

• macOS： 在桌面生成 Navidrome Player.app（如果愿意，可拖到 /Applications）。

• Windows： 在桌面和开始菜单生成 Navidrome Player.vbs。（如果桌面被 OneDrive 重定向，文件会放在那里。）

移动或重新构建项目后，请重新运行生成器以刷新路径。

配置

所有设置均为可选，位于设置页面的 Web UI 部分，下面按其在 settings.json 中的路径列出。保存后需重启客户端。例外是 persistAfterMcpExit，它通过齿轮弹窗实时生效。

用作手机/平板遥控器

1. 在设置页面启用 Expose on LAN 并保存。

2. 重启 MCP 客户端（或重启 navidrome-web）。

3. 播放器会在绑定时记录其可访问的局域网 URL（例如 http://192.168.1.42:8808）。在手机浏览器中打开其中一个并添加书签。

安全说明

Web UI 没有身份验证。任何能访问该端口的人都可以暂停、跳过、快进/快退、调节音量以及跳转队列。

• 使用 webui.host=127.0.0.1（默认值）时，只能从主机本身访问，这是安全的。

• 使用 Expose on LAN（webui.expose=true）时，局域网中的任何设备都可以访问。在可信的家庭网络中可以接受，但不要将其暴露到公共互联网。没有速率限制，控制 API 允许修改队列和启动播放列表。播放器设置和电源按钮仅限回环访问，对远程浏览器隐藏，因此局域网中的手机可以控制播放，但不能更改设置或关闭播放器。主设置页面永远不会被暴露。一旦暴露，GET /healthz 在主机之外返回 404，以避免泄露版本指纹，因此请从主机检查播放器的健康状况。

通过 HTTP 运行

默认情况下，服务器通过 stdio 提供 MCP 服务。客户端将其作为子进程启动，并通过 stdin/stdout 与之通信。这适用于同一台机器上的桌面客户端，但无法通过网络访问。

将传输方式设置为 http 后，服务器会绑定一个套接字，并在 /mcp 提供 MCP Streamable HTTP 传输服务。然后它作为独立进程运行，网络 MCP 客户端可直接连接，无需 supergateway 或 mcp-proxy 桥接。

在 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 永远不会被拦截。它是用于容器健康检查的未认证存活端点，返回 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（逗号分隔）。Web 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 支持（Web 和桌面版）需要托管的 HTTPS 端点，不适用于本地 stdio 服务器。此服务器可以通过 HTTP 提供 MCP 服务（参见通过 HTTP 运行），因此你可以将其托管在终止 TLS 的反向代理后面，而不是使用 mcp-remote 之类的桥接。对于自托管的音乐服务器，使用 Claude Desktop、Claude Code、Cursor 或其他支持 stdio 的客户端更简单。

故障排除

连接问题

• 确认 Navidrome 正在运行且可访问

• 确保设置页面中的 Navidrome URL 包含协议（http:// 或 https://）

• 保存前使用设置页面的 Test connection 按钮（或使用 curl / 浏览器测试凭据）

macOS 专属

• 参见 macOS 故障排除指南。常见问题是找不到 Node.js 路径，可通过符号链接或完整路径修复。

配置

• 在配置文件中使用绝对路径

• 验证 JSON（无尾随逗号）

• 更改后重启 MCP 客户端

已知限制

• 没有 mpv 就没有音频。 请改用 Navidrome Web UI 或 Subsonic 客户端（参见安装 mpv）。

• 最近播放没有时间戳。 Navidrome 只提供播放次数和完成状态，不提供曲目最后播放的时间。

• 已保存队列 ≠ 实时队列。 *_saved_queue 工具操作 Navidrome 服务端队列（Web 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

从开发构建测试独立 Web 播放器

这是在发布版本到达 npm 之前从源码尝试播放器的路径（已发布的包可能落后于 dev）。这也适用于 MCP 服务器，因为两者都从同一个 dist/ 运行。

# 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 社区倾心打造 ❤️