Navidrome MCP

导航MCP服务器

将您的Navidrome音乐服务器变成对话式音乐助手。此MCP（模型上下文协议）服务器允许Claude Desktop、Claude Code、Cursor和其他MCP兼容客户端浏览和管理您的库，构建播放列表，发现新音乐，并直接通过机器的扬声器播放音频。

目录

• 特性
• 安装
• MPV远程（Web UI）
• 可用工具
• 故障排除
• 发展
• 许可证

特性

🎵 音乐库

通过丰富的过滤功能浏览和搜索歌曲、专辑、艺术家、流派和标签：查询、星级状态、年份范围、排序顺序、标签值等。组合过滤器来询问以下问题 *“我90年代所有的明星爵士专辑，按年份排序”* 或 *“每首歌曲都以五星级评级标记为Soundtrack”*标签分析工具会显示库中的实际内容，这样您就不必猜测过滤器值。

🔊 本地音频播放

需要 mpv 在运行MCP服务器的主机上（请参见 安装mpv).

音频通过机器的扬声器播放，无需浏览器或Navidrome web UI。只需一步即可搜索和播放： *“随机播放5张明星专辑”*, *“按年份排列我90年代主演的所有电影”*, *“将10首随机摇滚歌曲添加到已经播放的歌曲中，随机播放”*专辑有三种洗牌模式（保持顺序、随机化专辑顺序、完全交错曲目）。

实时队列是可主动操纵的：将一首曲目移动到前面，它就开始播放，洗牌，新的顶级曲目播放，删除当前曲目，下一首曲目自动前进。保存的导航电台（Icecast、SHOUTcast等）通过mpv流式传输ICY元数据，以便您可以看到该电台当前正在播放的内容。将滚动播放回Navidrome，这样您最近播放的内容和播放次数就会与您通过mpv实际收听的内容保持同步。mpv在首次使用时是懒惰的，通过每个用户的套接字在MCP客户端重启后幸存下来，并在Linux、macOS和Windows 11上工作。

该设计专为对话式控制而设计，与语音传输（Whisper STT+TTS）完美结合，在Raspberry Pi或始终在线的机器上构建免提音乐设备。

🎛️ MPV远程（Web控制面板）

需要 mpv （与本地音频播放相同）。默认情况下打开；播放开始后，懒惰绑定。

配套的web UI位于 http://localhost:8808 用于从任何浏览器控制本地mpv播放。现在播放带有封面艺术、传输控制（上一页/暂停恢复/下一页）、搜索栏、音量滑块和点击跳转的队列列表的纸牌。通过服务器发送事件实时更新，这样放置在桌子上的手机就可以在助手向队列馈送时保持同步。默认值仅为localhost；翻转一个环境变量，将其暴露在局域网中，并将手机或平板电脑用作音乐遥控器。看 MPV远程（Web UI） 用于设置和安全说明。

🎶 播放列表

以对话方式创建、更新、重新排序和删除播放列表。通过一次操作灵活添加内容：单曲、整张专辑、整张艺术家唱片或特定光盘。查找包含给定歌曲的播放列表。根据收听数据构建动态播放列表： *“‘Hidden Gems’五星级歌曲播放列表，播放次数不超过5次”*, *“按时间顺序排列的前10位艺术家每张专辑中的一首热门歌曲”*.

🎼 音乐探索（Last.fm）

需要 LASTFM_API_KEY.免费钥匙在 last.fm/api.

查找相似的艺术家和曲目，获取传记和热门曲目，浏览全球音乐排行榜。结合您的库进行差距分析(*“按受欢迎程度排名的前5位艺术家中缺少的专辑”*)，重新发现被忽视的音乐(*“与我最喜欢的曲目相似，但从未播放过”*)，或根据您实际拥有的内容构建精心策划的“最佳”播放列表。

🎤 同步歌词

需要 LYRICS_PROVIDER=lrclib 和 LRCLIB_USER_AGENT。不需要API密钥。

从LRCLIB的社区数据库中获取具有毫秒精度时间戳（LRC格式）和纯文本回退的时间同步歌词。按标题、艺术家、专辑和持续时间自动匹配。

📻 网络收音机

管理Navidrome电台，并在全球范围内发现新的电台。流URL在添加之前经过验证（MP3、AAC、OGG、FLAC检测），并自动提取SHOUTcast/Ieccast元数据。支持批量维护： *“验证我的所有工作站并删除损坏的工作站”* 或 *“测试这10个URL并添加可用的URL”*.

通过无线电浏览器发现全球电台（需要 RADIO_BROWSER_USER_AGENT)涵盖数千个电台，可按流派、国家、语言、编解码器、比特率和受欢迎程度进行过滤，并提供投票和点击注册，以便您的使用情况为社区排名提供信息。

📊 听力分析

访问播放次数、最近播放的活动、评分最高和播放次数最多的列表，以及整个库中的标签分布。使用此功能驱动口味分析(*“今年我玩的类型更多，而不是更少”*)，发现被遗忘的收藏夹，找出你收藏中的热门奇迹，或者根据你的听力模式构建基于情绪的播放列表。

⭐ 评分和收藏夹

明星/非明星歌曲、专辑和艺术家，设置0-5星评级，并列出所有明星或最高评级的内容。读取和写入web UI用于跨设备同步的已保存Navidrome队列。

📚 多库支持

通过在客户端配置中设置默认值，将所有操作筛选到Navidrome库的一个子集(NAVIDROME_DEFAULT_LIBRARIES)或者在运行时切换活动库。

安装

先决条件

• Node.js 20+ (下载)
• 正在运行的Navidrome服务器
• MCP兼容客户端 （Claude Desktop、Claude Code、Cursor或其他支持本地stdio的MCP客户端）
• 可选： mpv 用于本地音频播放

快速设置

安装已发布的软件包（启动时自动更新）：

npm install -g navidrome-mcp

包裹： .

对于开发版本：

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

配置您的MCP客户端

对于Claude Desktop，编辑 claude_desktop_config.json （地点： %APPDATA%/Claude/ 在Windows上， ~/Library/Application Support/Claude/ 在macOS上， ~/.config/Claude/ 在Linux上）。其他MCP客户端使用相同的JSON形状。

{
  "mcpServers": {
    "navidrome": {
      "command": "npx",
      "args": ["navidrome-mcp"],
      "env": {
        "NAVIDROME_URL": "http://your-server:4533",
        "NAVIDROME_USERNAME": "your_username",
        "NAVIDROME_PASSWORD": "your_password",
        "NAVIDROME_DEFAULT_LIBRARIES": "1,2",
        "LASTFM_API_KEY": "your_api_key",
        "RADIO_BROWSER_USER_AGENT": "Navidrome-MCP/2.0 (+https://github.com/Blakeem/Navidrome-MCP)",
        "LYRICS_PROVIDER": "lrclib",
        "LRCLIB_USER_AGENT": "Navidrome-MCP/2.0 (+https://github.com/Blakeem/Navidrome-MCP)"
      }
    }
  }
}

对于手动构建，请替换 command/args 与：

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

必修的： NAVIDROME_URL, NAVIDROME_USERNAME, NAVIDROME_PASSWORD.

可选：

• NAVIDROME_DEFAULT_LIBRARIES：默认激活逗号分隔的库ID；省略所有库。
• LASTFM_API_KEY：启用Last.fm发现功能。
• RADIO_BROWSER_USER_AGENT：启用无线电浏览器全局电台发现。将项目URL替换为您自己的URL。
• LYRICS_PROVIDER=lrclib + LRCLIB_USER_AGENT：允许获取歌词。
• MPV_PATH：如果mpv二进制文件未打开，请指向它 PATH （例如。 "C:\\Program Files\\mpv\\mpv.exe").
• WEBUI_PORT / WEBUI_HOST / WEBUI_EXPOSE / WEBUI_ENABLED：配置 MPV远程web用户界面 --默认为 localhost:8808 一旦mpv开始播放，懒惰就会绑定。

当配置存在时，功能会自动打开。更改配置后重新启动MCP客户端。

安装mpv（可选）

mpv是一款轻量级的跨平台媒体播放器。在启动时检测到时，服务器会注册一组额外的播放工具，以便通过机器的扬声器播放音频。没有它，服务器仍然管理您的库和Navidrome的已保存队列；它只是不产生音频。

macOS （通过 家酿):

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

窗户：

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

使用完整的包ID shinchiro.mpv 跳过消歧提示；微软商店还列出了一个非官方的第三方 mpv 包装，朴素 winget install mpv 会要求你挑选。shinchiro建筑是社区的标准 mpv.io 它本身指向Windows。 视窗 PATH 注意。 这 shinchiro.mpv 机翼组件安装到 C:\Program Files\MPV Player\ 在Windows 11上 不 将自己添加到 PATH。您有两个选择： - 将安装文件夹添加到您的用户或系统 PATH （系统属性→ 环境变量→ Path → New → C:\Program Files\MPV Player)，然后打开一个新终端，使更改生效。 - 或设置 MPV_PATH 在MCP客户端配置中完全 mpv.exe 路径，例如。 "MPV_PATH": "C:\\Program Files\\MPV Player\\mpv.exe". 其他安装方法（勺式、巧克力式、mpv.io手动压缩） mpv.exe 在另一个文件夹中。如果 mpv --version 安装后在新终端中不起作用，请定位 mpv.exe 并应用上述两种修复方法之一。

或者一个预构建的二进制文件 mpv.io.验证 mpv --version，然后重新启动MCP客户端，以便服务器重新检测mpv。

关于ChatGPT桌面的说明

ChatGPT的MCP支持（web和桌面）需要一个托管的HTTPS端点，目前与像这样的本地stdio服务器不兼容。如果你真的想让它与ChatGPT一起工作，你可以使用类似的网桥将stdio服务器封装在HTTPS中 mcp-remote，但这增加了自托管音乐服务器的操作复杂性。否则，请使用Claude Desktop、Claude Code、Cursor或其他具有本机stdio支持的客户端。一旦OpenAI添加了第一方stdio MCP支持，请重新检查。

MPV远程（Web UI）

当本地音频播放处于活动状态时，MCP服务器会运行一个配套的web界面，该界面同时用作正在播放的显示器和传输控制遥控器。在主机上的任何浏览器中打开它（或者一旦暴露在局域网上的任何地方）。


它的作用

• 现在打牌 --封面艺术、标题、艺术家、专辑和排队位置。A. Live 指示器确认SSE流健康。
• 运输控制 --上一个/暂停恢复/下一个，搜索栏显示当前位置和剩余时间。
• 音量滑块 --驱动mpv的内部音量控制（独立于您的操作系统音量）。
• 队列列表 --当前mpv队列中的每首曲目都有标题、艺术家·专辑和持续时间。单击任意行以跳转到该行。
• 实时状态更新 --服务器发送事件推送状态会在事件发生的瞬间发生变化，被限制在~1Hz，因此进度条运行平稳，不会淹没网络。断开连接时，连接会自动重新连接。

启用

web UI是 默认开启 并绑定 懒洋洋地：端口仅在mpv有东西播放时打开，或者当服务器在MCP重新启动时重新连接到预先存在的mpv队列时打开。未安装mpv的主机根本看不到侦听器。

要完全关闭它，请设置 WEBUI_ENABLED=false 在MCP客户端的env块中。

配置

所有变量都是可选的。将它们添加到旁边 NAVIDROME_URL 在您的MCP客户的 env 块，然后重新启动客户端。

当 WEBUI_EXPOSE=true，MCP服务器记录绑定时可访问的LAN URL（例如。 http://192.168.1.42:8808).在手机或平板电脑上打开其中一个。

将其用作手机/平板电脑遥控器

1. 集 "WEBUI_EXPOSE": "true" 在MCP客户端的env块中。
2. 重新启动MCP客户端。
3. 触发任何播放（例如，要求助手 *“播放我所有的明星歌曲”*)--这就是导致web UI绑定的原因。
4. 从手机浏览器的启动日志中打开LAN URL。将其标记为书签，以便一键访问——该页面是一个单一的静态HTML/CSS/JS捆绑包，无需安装。

安全说明

web UI具有 无需认证 --任何能够到达该端口的人都可以暂停、跳过、查找、更改音量和在队列中跳转。

• 开 WEBUI_HOST=127.0.0.1 （默认）它只能从主机访问，这是安全的。
• 开 WEBUI_EXPOSE=true 它可以从局域网上的任何地方访问。在受信任的家庭网络上，这通常很好，但是 不要将其直接暴露在公共互联网上.没有速率限制，没有身份验证，并且控件API允许队列操作。

可用工具

标记的工具 条件性的 仅在存在相应配置时才注册。

核心系统

图书馆管理

搜索

播放列表

评分和收藏夹

收听历史记录和已保存队列

元数据和标签

Last.fm发现（需要 LASTFM_API_KEY)

歌词（必填） LYRICS_PROVIDER=lrclib + LRCLIB_USER_AGENT)

无线电管理

全球无线电发现（需要 RADIO_BROWSER_USER_AGENT)

本地播放（需要 mpv)

音频通过主持人的扬声器播放。mpv在首次使用时是延迟生成的，并通过每个用户的IPC套接字在MCP客户端重启后幸存下来。

故障排除

连接问题

• 验证Navidrome是否正在运行且可访问
• 确保 NAVIDROME_URL 包括协议(http:// 或 https://)
• 测试证书 curl 或先使用浏览器

macOS特定

• 看 macOS故障排除指南 （通常：找不到Node.js路径；用符号链接或完整路径修复）

配置

• 在配置文件中使用绝对路径
• 验证JSON（无尾随逗号）
• 更改后重新启动MCP客户端

已知限制

• 没有mpv就没有音频。 当mpv未安装时，库和保存的队列工具仍然可以工作，但音频播放不可用；使用Navidrome web UI或Subsonic客户端。
• 最近播放的游戏没有时间戳。 Navidrome显示播放次数和完成状态，而不是上次播放的时间。
• 已保存队列≠实时队列。 这 *_saved_queue 这些工具在Navidrome的服务器端咨询队列（web UI同步）上运行。这 *_play_queue 工具对本地mpv播放列表进行操作。他们是独立的。

发展

git clone https://github.com/Blakeem/Navidrome-MCP.git
cd Navidrome-MCP
cp .env.example .env
# Edit .env with your credentials

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

测试与 MCP检查员:

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

支持

______________________________________________________________________

建于❤️ 为Navidrome社区