Navidrome MCP

🚀 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 包（推荐）

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

使用手动构建（可选）

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

💻 使用示例

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

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

🔍 收藏缺口分析

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

📻 广播电台维护

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

🎼 高级播放列表自动化

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

📊 收听洞察与整理

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

📚 详细文档

可用工具

🔧 核心系统

📚 音乐库管理

🔍 搜索与发现

🎵 播放列表操作

⭐ 评级与收藏

📊 分析与历史

📻 广播管理

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

🎤 歌词与时间戳

🏷️ 元数据与标签

🔧 技术细节

常见问题

连接问题

• 验证 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 社区用心打造 ❤️