Navidrome MCP

🚀 Navidrome MCP Server

AI技術を搭載した音楽アシスタントにより、Navidrome音楽サーバーを一新します。このMCP（Model Context Protocol）サーバーを使用すると、ClaudeやChatGPTなどのAIアシスタントが自然言語で個人の音楽ライブラリと対話でき、インテリジェントなプレイリスト作成、音楽発見、ライブラリ管理が可能になります。

🚀 クイックスタート

このセクションでは、Navidrome MCP Serverの概要と、なぜこのサーバーが必要なのかを説明します。また、その機能やインストール方法、使い方の例なども紹介します。

✨ 主な機能

🎵 音楽ライブラリ管理

• インテリジェントな閲覧：スマートなフィルタリング機能を使って、曲、アルバム、アーティスト、ジャンルをナビゲートできます。
• 深い検索：すべてのメタデータに対する全文検索や、特定の内容に対するターゲット検索が可能です。
• 豊富なメタデータ：曲、アルバム、アーティストに関する詳細な情報にアクセスできます。
• タグ分析：メタデータタグ（ジャンル、作曲家、レーベル、年など）を探索および分析できます。
• クリーンなレスポンス：必要なフィールドのみを使用した最適化されたデータ転送（約10のプロパティ対50以上の生データ）。

🎶 インテリジェントなプレイリスト作成

• AIアシスタント統合：AIアシスタントがユーザーの嗜好を分析し、テーマ別のプレイリストを作成できます。
• スマートな管理：会話形式でプレイリストを作成、更新、整理できます。
• 柔軟なトラック追加：IDで曲を追加したり、アルバム全体、アーティストのディスコグラフィ、特定のディスクを追加できます。
• 動的な並べ替え：簡単なコマンドでトラックを並べ替えられます。
• 相互参照：特定の曲が含まれるプレイリストを見つけることができます。

🎼 パーソナライズドな音楽発見

• 聴取データアクセス：AIアシスタントがユーザーの嗜好を理解するための聴取履歴データを提供します。
• 類似アーティスト/トラック検索：Last.fmを使って、お気に入りの音楽に似た曲を発見できます。
• アーティストの深掘り：アーティストの伝記、人気の曲、関連アーティストを取得できます。
• グローバルなトレンド：世界中の音楽チャートや流行のジャンルを閲覧できます。
• ライブラリ分析ツール：AIアシスタントがライブラリ内の見落とされた曲を見つけるのに役立つデータにアクセスできます。

📻 スマートなラジオ管理

• ストリーム検証：ラジオURLを追加する前にテストし、壊れたストリームを避けることができます。
• 形式検出：MP3、AAC、OGG、FLACストリームを自動検出します。
• メタデータ抽出：SHOUTcast/Icecastヘッダーからステーション情報を取得します。
• カスタムステーション作成：お気に入りの曲からラジオ局を作成できます。
• ワンタイムセットアップヒント：必要なときにのみ表示されるスマートなコンテキストヘルプ。

🌍 インターネットラジオ発見

• グローバルなステーションデータベース：Radio Browserを通じて、世界中の数千のインターネットラジオ局にアクセスできます。
• 高度なフィルタリング：ジャンル、国、言語、コーデック、ビットレートなどで検索できます。
• 自動検証：発見されたステーションの可用性をテストします。
• 品質管理：壊れたステーションを除外し、高品質のストリームに焦点を当てます。
• 人気指標：投票数やリスナーの関与度でステーションを発見できます。
• ステーション管理：AIアシスタントが発見したステーションをコレクションに追加するためのツール。

🎤 同期歌詞

• 時間同期歌詞：ミリ秒精度のタイムスタンプ付きの歌詞を取得でき、1行ごとのタイミングが可能です。
• デュアルフォーマットサポート：時間同期歌詞と平文歌詞の両方にアクセスできます。
• コミュニティ主導：歌詞はLRCLIBのコミュニティデータベースから取得されます。
• スマートなマッチング：タイトル、アーティスト、アルバム、再生時間で自動的にマッチングします。
• APIキー不要：登録なしで無料で歌詞にアクセスできます。

📊 分析と洞察

• 聴取パターン：再生統計を使って、音楽の使用習慣を理解できます。
• 嗜好の進化：時間の経過とともに、ユーザーの嗜好がどのように変化したかを追跡できます。
• 最も/最も少なく再生された曲：本当のお気に入りの曲と忘れられた曲を発見できます。
• ジャンル分布：ライブラリの構成に関するデータにアクセスし、分析できます。
• 推薦データ：AIアシスタントがユーザーの履歴に基づいて提案を生成するためのデータを提供します。

⭐ 嗜好管理

• スターシステム：お気に入りをマークして、すぐにアクセスできるようにします。
• 5段階評価：コンテンツに評価を付けて、より良い推薦を受けることができます。
• キュー管理：デバイス間で再生キューを管理できます。
• 整理のためのデータアクセス：AIアシスタントがコレクションを整理するのに役立つ嗜好データを提供します。

📦 インストール

前提条件

• Node.js 20+ (ここからダウンロード)
• 音楽ライブラリを持つ稼働中のNavidromeサーバー
• Claude Desktop または ChatGPT Desktop（またはMCP互換のクライアント）

手動ビルドの追加要件：

• pnpm パッケージマネージャー (インストール方法)

クイックセットアップ

方法1：NPMパッケージ（推奨）

最も簡単な開始方法は、公開されているnpmパッケージを使用することです。これは起動時に自動更新されます。

npm install -g navidrome-mcp

📦 パッケージ：navidrome-mcp on npm

これにより、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 で取得
        "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 で取得
        "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 で無料のLast.fm APIキーを取得できます（オプション - 音楽発見機能を有効にする）。
• Radio Browserの統合にはUser-Agent文字列が必要です（ステーション発見機能を有効にする）。
• 歌詞の統合は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のトップトラックデータを使って、'Best of Pink Floyd' プレイリストを作成するが、実際に所有している曲のみを使用する」
• 「最近再生した曲を分析し、ライブラリ内で6ヶ月間再生していない類似の曲を見つけ、再発見用のプレイリストを作成する」
• 「最も再生回数の多い上位10曲と、所有しているがあまり聴かないアーティストの類似の曲を混ぜたプレイリストを作成する」

🔍 コレクションのギャップ分析

• 「最も再生回数の多い上位5アーティストから欠けているアルバムを表示し、Last.fmの人気度でランク付けする」
• 「シングルまたはコンピレーションのみを所有し、メインアルバムを持っていないアーティストを見つける」
• 「お気に入りのジャンルを特定し、それらのジャンルで高評価のアルバムで、所有していないものを表示する」
• 「お気に入りのアーティストに似たアーティストを見て、ライブラリ内にあるが一度も再生していないアーティストを教えて」

📻 ラジオ局のメンテナンス

• 「すべての既存のラジオ局を確認し、各局を検証し、壊れた局を削除する」
• 「オンラインで見つけた10のジャズラジオURLをすべてテストし、良好なビットレートの動作する局のみを追加する」
• 「世界中で最も投票数の多いジャズとクラシックの局を見つけ、検証し、各ジャンルの上位5局を追加する」
• 「すべてのラジオ局をチェックし、壊れた局を類似の動作する局に置き換える」

🎼 高度なプレイリスト自動化

• 「再生回数が5回未満の5つ星評価の曲で、'Hidden Gems' プレイリストを作成する」
• 「昨年の各月で最も多く聴いた音楽に基づいて、毎週のプレイリストを作成する」
• 「上位10アーティストの各アルバムから1つのトップトラックを選び、年代順に並べた'Complete Artist Journey' プレイリストを作成する」
• 「聴取パターンを分析して、朝、夜、週末に再生する曲に基づいて、ムード別のプレイリストを生成する」

📊 聴取洞察と整理

• 「ジャズコレクションを分析する：再生回数、評価を表示し、一度も完全に聴いていないアルバムを見つける」
• 「異なるアルバム間の重複する曲を見つけ、クリーンアップリストを作成する」
• 「聴取の進化を表示する：どのジャンルから離れ、どのジャンルをより多く再生しているかを示す」
• 「ライブラリ内の'ワンヒットウンダー'を特定する - 1曲のみを繰り返し再生するアーティスト」

📚 ドキュメント

利用可能なツール

トラブルシューティング

一般的な問題

• 接続問題
  • Navidromeサーバーが稼働していることを確認します。
  • URLにプロトコル（http:// またはhttps://）が含まれていることを確認します。
  • 資格情報が正しいことを確認します。
  • 最初に curl またはブラウザでテストします。
• macOS固有の問題
  • macOSトラブルシューティングガイド を参照してください。
  • 一般的な問題：Node.jsのパスが見つからない。
  • 解決策：シンボリックリンクを作成するか、完全なパスを使用します。
• 設定問題
  • 設定ファイルで絶対パスを使用します。
  • JSON構文を検証します（末尾のカンマは使用しない）。
  • 環境変数が設定されていることを確認します。
  • 変更後にクライアントを再起動します。

制限事項

• 再生制御：このMCPサーバーはライブラリとキューを管理しますが、直接的な再生制御は行いません。再生/一時停止/スキップにはNavidromeクライアントアプリを使用してください。
• 最近再生された曲：Navidromeは最後の再生タイムスタンプを提供せず、再生回数と再生完了ステータスのみを提供します。
• キュー管理：ジュークボックスモードをサポートする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

# Web 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      # AIアシスタントの指示書

📄 ライセンス

コード：AGPL - 3.0

ソースコードはGNU Affero General Public License v3.0の下でライセンスされています。詳細は LICENSE を参照してください。

ドキュメント：CC - BY - SA - 4.0

ドキュメントはCreative Commons Attribution - ShareAlike 4.0 Internationalの下でライセンスされています。

サポート

• 問題報告：GitHub Issues
• 議論：GitHub Discussions

Navidromeコミュニティのために愛情を込めて作成されました