金大哥 - navidrome-mcp MCP 详情

article

README

🚀 Navidrome MCP 服务器

借助由人工智能驱动的音乐助手，对您的 Navidrome 音乐服务器进行改造。此 MCP（模型上下文协议）服务器使 Claude、ChatGPT 等人工智能助手能够通过自然语言与您的个人音乐库进行交互，实现智能播放列表创建、音乐发现和音乐库管理等功能。

🚀 快速开始

本 MCP 服务器能让人工智能助手真正理解您的音乐品味，实现以下功能：

分析您的收听模式，创建精心策划的播放列表。
根据您的心情或活动，在您的音乐库中发掘隐藏的宝藏曲目。
基于您喜爱的曲目创建自定义广播电台。
利用 Last.fm 的推荐引擎，查找与您喜爱的音乐相似的曲目。
通过高级过滤功能，发现来自世界各地的网络广播电台。
为您喜爱的曲目提供具有毫秒级精度时间戳的同步歌词。
通过简单的对话式命令管理您的音乐库。

这不仅仅是另一个音乐工具，而是由人工智能驱动的个人音乐策划师。

✨ 主要特性

🎵 音乐库管理

智能浏览：通过智能过滤功能浏览歌曲、专辑、艺术家和流派。
深度搜索：对所有元数据进行全文搜索，或针对特定内容进行有针对性的搜索。
丰富的元数据：访问有关曲目、专辑和艺术家的详细信息。
标签分析：探索和分析元数据标签（流派、作曲家、唱片公司、年份等）。
简洁响应：优化数据传输，仅包含必要字段（约 10 个属性，而非 50 多个原始属性）。

🎶 智能播放列表创建

人工智能助手集成：使人工智能助手能够分析您的品味并创建主题播放列表。
智能管理：通过对话方式创建、更新和组织播放列表。
灵活的曲目添加：通过 ID、整个专辑、艺术家的全部作品或特定唱片添加歌曲。
动态重新排序：通过简单的命令重新排列曲目。
交叉引用：查找包含特定歌曲的播放列表。

🎼 个性化音乐发现

收听数据访问：为人工智能助手提供收听历史数据，以了解您的偏好。
相似艺术家/曲目查找：通过 Last.fm 发现与您喜爱的音乐相似的曲目。
艺术家深度探索：获取艺术家的传记、热门曲目和相关艺术家信息。
全球趋势：浏览全球音乐排行榜和热门流派。
音乐库分析工具：提供数据，帮助人工智能助手发现您音乐库中被忽视的曲目。

📻 智能广播管理

流验证：在添加广播 URL 之前进行测试，避免出现播放中断的情况。
格式检测：自动检测 MP3、AAC、OGG、FLAC 流。
元数据提取：从 SHOUTcast/Icecast 标头中提取电台信息。
自定义电台创建：根据您喜爱的曲目创建广播电台。
一次性设置提示：仅在需要时提供智能上下文帮助。

🌍 网络广播发现

全球电台数据库：通过 Radio Browser 访问全球数千个网络广播电台。
高级过滤：按流派、国家、语言、编解码器、比特率等进行搜索。
自动验证：对发现的电台进行可用性测试。
质量控制：过滤掉无法播放的电台，专注于高质量的流。
人气指标：根据投票数和听众参与度发现电台。
电台管理：为人工智能助手提供工具，将发现的电台添加到您的收藏中。

🎤 同步歌词

时间同步歌词：提供具有毫秒级精度时间戳的歌词，实现逐行同步。
双格式支持：支持时间同步和纯文本歌词。
社区驱动：歌词来源于 LRCLIB 的社区数据库。
智能匹配：根据标题、艺术家、专辑和时长自动匹配歌词。
无需 API 密钥：免费访问歌词，无需注册。

📊 分析与洞察

收听模式：通过播放统计数据了解您的音乐习惯。
品味演变：跟踪您的音乐偏好随时间的变化。
播放最多/最少的曲目：发现您真正喜爱的曲目和被遗忘的曲目。
流派分布：获取有关您音乐库组成的数据，以便进行分析。
推荐数据：为人工智能助手提供数据，根据您的历史记录生成推荐。

⭐ 偏好管理

收藏系统：标记喜爱的曲目，以便快速访问。
五星评级：对内容进行评级，以获得更好的推荐。
播放队列控制：跨设备管理播放队列。
组织数据访问：为人工智能助手提供偏好数据，帮助您组织音乐收藏。

📦 安装指南

前提条件

Node.js 20+（在此下载）
运行中的 Navidrome 服务器，并已添加您的音乐库
Claude Desktop 或 ChatGPT Desktop（或任何支持 MCP 的客户端）

手动构建的额外要求：

pnpm 包管理器（安装说明）

快速设置

方法 1：NPM 包（推荐）

最简单的开始方式是使用已发布的 npm 包，该包在启动时会自动更新：

npm install -g navidrome-mcp

📦 包：npm 上的 navidrome-mcp

此方法会全局安装 MCP 服务器，并自动保持其最新状态。

方法 2：手动构建（开发用）

如果您需要进行开发或自定义构建，请执行以下操作：

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

配置 Claude Desktop

找到您的配置文件：

Windows：%APPDATA%/Claude/claude_desktop_config.json
macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Linux：~/.config/Claude/claude_desktop_config.json

添加 Navidrome MCP 服务器：

使用 NPM 包（推荐）

{
  "mcpServers": {
    "navidrome": {
      "command": "npx",
      "args": ["navidrome-mcp"],
      "env": {
        "NAVIDROME_URL": "http://your-server:4533",
        "NAVIDROME_USERNAME": "your_username",
        "NAVIDROME_PASSWORD": "your_password",
        "LASTFM_API_KEY": "your_api_key", // 在 https://www.last.fm/api/account/create 获取您自己的 API 密钥
        "RADIO_BROWSER_USER_AGENT": "Navidrome-MCP/1.0 (+https://github.com/Blakeem/Navidrome-MCP)",
        "LYRICS_PROVIDER": "lrclib",
        "LRCLIB_USER_AGENT": "Navidrome-MCP/1.0 (+https://github.com/Blakeem/Navidrome-MCP)"
      }
    }
  }
}

使用手动构建（可选）

{
  "mcpServers": {
    "navidrome": {
      "command": "node",
      "args": ["/absolute/path/to/navidrome-mcp/dist/index.js"],
      "env": {
        "NAVIDROME_URL": "http://your-server:4533",
        "NAVIDROME_USERNAME": "your_username",
        "NAVIDROME_PASSWORD": "your_password",
        "LASTFM_API_KEY": "your_api_key", // 在 https://www.last.fm/api/account/create 获取您自己的 API 密钥
        "RADIO_BROWSER_USER_AGENT": "Navidrome-MCP/1.0 (+https://github.com/Blakeem/Navidrome-MCP)",
        "LYRICS_PROVIDER": "lrclib",
        "LRCLIB_USER_AGENT": "Navidrome-MCP/1.0 (+https://github.com/Blakeem/Navidrome-MCP)"
      }
    }
  }
}

重要提示：

NPM 方法：使用 npx navidrome-mcp，每次启动时会自动更新。
手动方法：需要使用绝对路径（从根目录开始的完整路径），并手动更新。
您可以在 Last.fm 免费获取 API 密钥（可选 - 启用音乐发现功能）。
广播浏览器集成需要用户代理字符串（启用电台发现功能）。
歌词集成无需 API 密钥（LRCLIB 是免费的）。
功能会根据可用配置自动启用或禁用。
保存配置后，重启 Claude Desktop。

配置 ChatGPT Desktop

使用 NPM 包（推荐）

打开 ChatGPT Desktop。
转到 设置 → 连接器。
点击创建并添加以下内容：
- 命令：npx
- 参数：navidrome-mcp
- 环境变量：与上述相同。
保存并重启。

使用手动构建（可选）

打开 ChatGPT Desktop。
转到 设置 → 连接器。
点击创建并添加以下内容：
- 命令：node
- 参数：/absolute/path/to/navidrome-mcp/dist/index.js
- 环境变量：与上述相同。
保存并重启。

💻 使用示例

🎯 智能发现与播放列表创建

“查看我播放最多的艺术家，找出他们作品中我缺失的专辑，并告诉我哪些最受欢迎”
“使用 Last.fm 的热门曲目数据创建一个‘平克·弗洛伊德精选’播放列表，但只包含我实际拥有的歌曲”
“分析我最近播放的歌曲，在我的音乐库中找到 6 个月内未播放过的相似曲目，并创建一个重温播放列表”
“为我创建一个播放列表，将我播放最多的前 10 首歌曲与我拥有但很少收听的艺术家的相似曲目混合在一起”

🔍 收藏缺口分析

“显示我播放最多的前 5 位艺术家缺失的专辑，并按 Last.fm 的人气排名”
“查找我只拥有单曲或合辑，而没有其主要专辑的艺术家”
“确定我最喜欢的流派，然后向我展示这些流派中我没有的高评分专辑”
“查看与我喜欢的艺术家相似的艺术家，并告诉我哪些我已经在音乐库中但从未播放过”

📻 广播电台维护

“检查我所有现有的广播电台，验证每个电台，并删除无法播放的电台”
“这是我在网上找到的 10 个爵士广播 URL - 测试所有这些 URL，只添加那些能正常播放且比特率良好的电台”
“查找全球投票最多的爵士和古典电台，验证它们，并添加每个流派中最好的 5 个电台”
“检查我所有的广播电台，用相似的正常电台替换任何无法播放的电台”

🎼 高级播放列表自动化

“创建一个‘隐藏宝藏’播放列表，包含评分 5 星但播放次数少于 5 次的歌曲”
“根据我去年每个月收听最多的内容创建每周播放列表”
“创建一个‘完整艺术家旅程’播放列表，按时间顺序从我的前 10 位艺术家的每张专辑中选取一首热门曲目”
“通过分析我的收听模式生成心情播放列表：我在早上、晚上和周末分别播放什么”

📊 收听洞察与整理

“分析我的爵士音乐收藏：显示播放次数、评分，并找出我从未完整收听的专辑”
“查找不同专辑中的重复歌曲，并创建一个清理列表”
“展示我的收听演变：我不再关注哪些流派，以及哪些流派我收听得更多”
“识别我音乐库中的‘一鸣惊人’艺术家 - 即我只反复播放他们一首歌曲的艺术家”

📚 详细文档

可用工具

🔧 核心系统

| 工具 | 描述 | |------|------| | test_connection | 验证 Navidrome 服务器的连接性和功能状态 |

📚 音乐库管理

| 工具 | 描述 | |------|------| | list_songs | 通过过滤和排序浏览歌曲 | | list_albums | 浏览带有元数据的专辑 | | list_artists | 浏览带有统计信息的艺术家 | | list_genres | 查看音乐库中的所有音乐流派 | | get_song | 获取详细的歌曲信息 | | get_album | 获取详细的专辑信息 | | get_artist | 获取详细的艺术家信息 | | get_song_playlists | 获取包含特定歌曲的所有播放列表 |

🔍 搜索与发现

| 工具 | 描述 | |------|------| | search_all | 在所有内容类型中进行搜索 | | search_songs | 搜索特定歌曲 | | search_albums | 搜索专辑 | | search_artists | 搜索艺术家 | | get_similar_artists | 查找相似的艺术家（Last.fm） | | get_similar_tracks | 查找相似的曲目（Last.fm） | | get_artist_info | 获取艺术家的传记和标签信息 | | get_top_tracks_by_artist | 从 Last.fm 获取艺术家的热门曲目 | | get_trending_music | 查看全球音乐趋势 |

🎵 播放列表操作

| 工具 | 描述 | |------|------| | list_playlists | 查看所有播放列表 | | get_playlist | 根据 ID 获取特定播放列表的详细信息 | | create_playlist | 创建新的播放列表 | | update_playlist | 更新播放列表的元数据 | | delete_playlist | 删除播放列表 | | get_playlist_tracks | 获取播放列表的内容 | | add_tracks_to_playlist | 添加歌曲/专辑/艺术家 | | batch_add_tracks_to_playlist | 批量添加多组曲目 | | remove_tracks_from_playlist | 删除特定曲目 | | reorder_playlist_track | 重新排列曲目顺序 |

⭐ 评级与收藏

| 工具 | 描述 | |------|------| | star_item | 将项目标记为收藏 | | unstar_item | 从收藏中移除项目 | | set_rating | 设置 0 - 5 星评级 | | list_starred_items | 查看收藏项目 | | list_top_rated | 查看评分最高的项目 |

📊 分析与历史

| 工具 | 描述 | |------|------| | list_recently_played | 查看最近的收听活动 | | list_most_played | 查找播放最多的内容 | | get_queue | 查看播放队列 | | set_queue | 设置播放队列 | | clear_queue | 清空播放队列 |

📻 广播管理

| 工具 | 描述 | |------|------| | validate_radio_stream | 测试广播流 URL 的有效性 | | list_radio_stations | 查看所有广播电台 | | get_radio_station | 根据 ID 获取特定广播电台的详细信息 | | create_radio_station | 添加新的广播电台（可选验证*） | | delete_radio_station | 根据 ID 删除网络广播电台 | | batch_create_radio_stations | 批量添加多个广播电台（可选验证*） | | play_radio_station | 开始广播播放 | | get_current_radio_info | 获取当前播放的广播电台和流元数据的信息 | | discover_radio_stations | 在全球范围内查找网络广播电台 | | get_radio_filters | 获取可用的搜索过滤器（流派、国家等） | | get_station_by_uuid | 获取详细的电台信息 | | click_station | 记录播放点击以用于人气指标 | | vote_station | 为广播电台投票 |

*注意：create_radio_station 和 batch_create_radio_stations 都支持一个可选的 validateBeforeAdd 参数，该参数会在将广播流 URL 添加到 Navidrome 之前对其进行测试。

🎤 歌词与时间戳

| 工具 | 描述 | |------|------| | get_lyrics | 获取同步和纯文本歌词 |

🏷️ 元数据与标签

| 工具 | 描述 | |------|------| | list_tags | 浏览所有元数据标签 | | get_tag | 根据 ID 获取特定标签的详细信息 | | search_by_tags | 根据特定标签进行搜索 | | get_tag_distribution | 分析标签使用情况 | | list_unique_tags | 列出所有唯一的标签名称并附带统计信息（唯一值数量、总使用次数） |

🔧 技术细节

常见问题

连接问题

验证 Navidrome 服务器是否正在运行。
检查 URL 是否包含协议（http:// 或 https://）。
确保凭据正确。
先使用 curl 或浏览器进行测试。

macOS 特定问题

请参阅 macOS 故障排除指南。
常见问题：找不到 Node.js 路径。
解决方案：创建符号链接或使用完整路径。

配置问题

在配置文件中使用绝对路径。
验证 JSON 语法（无尾随逗号）。
检查环境变量是否已设置。
更改配置后，重启客户端。

限制

播放控制：此 MCP 服务器管理您的音乐库和队列，但不直接控制播放。请使用您的 Navidrome 客户端应用进行播放、暂停、跳过等操作。
最近播放：Navidrome 不提供最后播放时间戳，仅提供播放次数和播放完成状态。
队列管理：适用于支持 jukebox 模式的 Subsonic 兼容客户端。

开发设置

贡献者设置

# 克隆并设置项目
git clone https://github.com/Blakeem/Navidrome-MCP.git
cd navidrome-mcp
cp .env.example .env
# 使用您的凭据编辑 .env 文件

# 开发
pnpm dev       # 热重载模式
pnpm test      # 运行测试
pnpm lint      # 检查代码风格
pnpm typecheck # 类型检查

使用 MCP 检查器进行测试

# 首先进行构建
pnpm build

# 网页 UI 测试
npx @modelcontextprotocol/inspector node dist/index.js

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

项目结构

navidrome-mcp/
├── src/           # TypeScript 源代码
├── dist/          # 编译后的 JavaScript
├── docs/          # 文档
├── tests/         # 测试套件
└── CLAUDE.md      # 人工智能助手说明

📄 许可证

代码：AGPL - 3.0

源代码遵循 GNU Affero 通用公共许可证 v3.0。请参阅 LICENSE。

文档：CC - BY - SA - 4.0

文档遵循知识共享署名 - 相同方式共享 4.0 国际许可协议。

支持

问题反馈：GitHub 问题
讨论交流：GitHub 讨论

为 Navidrome 社区用心打造 ❤️

navidrome-mcp

README

🚀 Navidrome MCP 服务器

🚀 快速开始

✨ 主要特性

🎵 音乐库管理

🎶 智能播放列表创建

🎼 个性化音乐发现

📻 智能广播管理

🌍 网络广播发现

🎤 同步歌词

📊 分析与洞察

⭐ 偏好管理

📦 安装指南

前提条件

快速设置

方法 1：NPM 包（推荐）

方法 2：手动构建（开发用）

配置 Claude Desktop

使用 NPM 包（推荐）

使用手动构建（可选）

配置 ChatGPT Desktop

使用 NPM 包（推荐）

使用手动构建（可选）

💻 使用示例

🎯 智能发现与播放列表创建

🔍 收藏缺口分析

📻 广播电台维护

🎼 高级播放列表自动化

📊 收听洞察与整理

📚 详细文档

可用工具

🔧 核心系统

📚 音乐库管理

🔍 搜索与发现

🎵 播放列表操作

⭐ 评级与收藏

📊 分析与历史

📻 广播管理

🎤 歌词与时间戳

🏷️ 元数据与标签

🔧 技术细节

常见问题

连接问题

macOS 特定问题

配置问题

限制

开发设置

贡献者设置

使用 MCP 检查器进行测试

项目结构

📄 许可证

代码：AGPL - 3.0

文档：CC - BY - SA - 4.0

支持

运行方式说明

托管运行

本地运行 / 其它方式