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 社區用心打造 ❤️