Local Music Collection Mcp

Music Collection MCP サーバー

高度なメタデータ管理、アルバムタイプ分類、包括的な分析を通じて、ローカルの音楽コレクションにインテリジェントにアクセスできる強力な Model Context Protocol（MCP）サーバーです。

✨ 主な機能

• 🎵 スマートな音楽検索：8 種類のアルバム分類（Album、EP、Live、Demo、Compilation、Single、Instrumental、Split）によるインテリジェントなスキャン
• 📊 高度な分析：コレクションの成熟度評価、健全性スコア、パーソナライズされたおすすめ
• 🏗️ 柔軟な整理：複数のフォルダー構成に対応し、自動移行と準拠スコアリングを提供
• ⚡ 高パフォーマンス：最適化されたスキャン（20〜30％高速化）、バッチ操作、インテリジェントなキャッシュ
• 🤖 AI 連携：Claude Desktop やその他の MCP クライアントとシームレスに連携
• 🔄 セットアップの自動化：1 つのコマンドでインストールし、設定を生成

🚀 クイックスタート

オプション 1：自動セットアップ（推奨）

python scripts/setup.py

このガイド付きセットアップでは、以下を行います。

• システム要件を確認する
• 依存関係をインストールする
• 音楽コレクションのパスを設定する
• Claude Desktop の設定を生成する
• セットアップを検証する

オプション 2：手動インストール

Python を使用

# Install dependencies
pip install -r requirements.txt

# Set your music path
export MUSIC_ROOT_PATH="/path/to/your/music"

# Run the server
python main.py

Docker を使用

# Build and run
docker build -t music-mcp .
docker run -v "/path/to/your/music:/music" -e MUSIC_ROOT_PATH=/music music-mcp

🤖 MCP クライアントのセットアップ

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

Python のインストール

{
  "mcpServers": {
    "music-collection": {
      "command": "python",
      "args": ["/path/to/music-mcp-server/main.py"],
      "env": {
        "MUSIC_ROOT_PATH": "/path/to/your/music",
        "CACHE_DURATION_DAYS": "30",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Docker のインストール

{
  "mcpServers": {
    "music-collection": {
      "command": "docker",
      "args": [
        "run", "--rm", "--interactive",
        "-v", "/path/to/your/music:/music",
        "-e", "MUSIC_ROOT_PATH=/music",
        "-e", "CACHE_DURATION_DAYS=30",
        "music-mcp"
      ]
    }
  }
}

📁 音楽の整理

このサーバーは複数の整理パターンに対応しています。

拡張構成（推奨）

Band Name/
├── Album/
│   ├── 1973 - Dark Side of the Moon/
│   └── 1979 - The Wall (Deluxe)/
├── Live/
│   └── 1988 - Delicate Sound of Thunder/
├── Compilation/
│   └── 2001 - Echoes - Best Of/
└── .band_metadata.json (auto-generated)

シンプルな構成（こちらも対応）

Band Name/
├── 1973 - Dark Side of the Moon/
├── 1988 - Delicate Sound of Thunder (Live)/
└── 2001 - Echoes - Best Of (Compilation)/

🛠️ MCP の機能

ツール（全 10 種類）

• 音楽の検索：scan_music_folders - タイプ検出機能を備えたスマートスキャン
• コレクション管理：get_band_list - 高度な絞り込みと検索
• メタデータの保存：save_band_metadata、save_band_analyze、save_collection_insight
• 検証：validate_band_metadata - ドライラン検証
• 高度な検索：advanced_search_albums - 13 個のパラメーターによる絞り込みシステム
• 分析：analyze_collection_insights - 包括的なコレクション分析
• 構成の移行：migrate_band_structure - 安全なフォルダー構成の移行

リソース（全 3 種類）

• バンド情報：band://info/{band_name} - バンドの詳細情報
• コレクションの概要：collection://summary - 概要と統計情報
• 高度な分析：collection://analytics - コレクションの詳細分析

プロンプト（全 4 種類）

• 情報収集：fetch_band_info、analyze_band
• 分析：compare_bands、collection_insights

⚙️ 設定

環境変数または自動セットアップを使用して設定します。

MUSIC_ROOT_PATH="/path/to/your/music"     # Required: Your music directory
CACHE_DURATION_DAYS=30                    # Optional: Cache expiration (default: 30)
LOG_LEVEL=INFO                           # Optional: Logging level (default: INFO)

📚 ドキュメント

すぐに始める

• クイックスタートガイド - 数分で実行できます
• インストールガイド - 詳細なセットアップ手順
• 設定ガイド - 高度な設定オプション

詳しく知る

• 使用例 - 実際の使用例
• コレクションの整理 - ベストプラクティス
• アルバムの取り扱い - アルバムタイプについて

ヘルプを利用する

• FAQ - よくある質問
• トラブルシューティング - 問題の解決方法
• 評価システム - 評価と分析について

🔧 メンテナンスとスクリプト

scripts/ ディレクトリには、強力なメンテナンスツールが用意されています。

• セットアップ: setup.py - インストールと設定を自動化します
• Docker: start-docker.sh - オプションを指定してコンテナを管理します
• 検証: validate-music-structure.py - コレクションの健全性をチェックします
• バックアップ: backup-recovery.py - 完全なバックアップと復旧システムです
• モニタリング: health-check.py - 包括的な健全性モニタリングを行います

🧪 テスト

# Using Docker (recommended)
docker build -f Dockerfile.test -t music-mcp-tests .
docker run --rm music-mcp-tests python -m pytest . -v

# Using Python
python -m pytest tests/ -v

📊 新着情報

最近の改善

• 移行ツール: バックアップとロールバックに対応した、安全なフォルダー構造の移行
• 高度な分析: コレクションの成熟度評価と健全性スコアリング
• パフォーマンス: ファイル操作の最適化により、スキャンを20～30%高速化
• スキーマの分離: 管理を改善するため、ローカルのアルバムと不足しているアルバムを分離
• 自動セットアップ: 1つのコマンドでインストールと設定を実行
• アルバムの種類: 8種類のインテリジェントな分類システム
• 柔軟な構造: 複数の整理パターンに対応

🆘 お困りですか？

1. よくある質問については、FAQを確認してください
2. 健全性チェックを実行: python scripts/health-check.py /path/to/music
3. 構造を検証: python scripts/validate-music-structure.py /path/to/music
4. トラブルシューティングガイドを確認してください

🔗 リンク

• セットアップスクリプト: scripts/ ディレクトリに、完全な自動化機能があります
• Claude Desktop の設定: scripts/claude-desktop-configs/ に、そのまま使える例があります
• 開発者向けドキュメント: docs/developer/ に、アーキテクチャと API リファレンスがあります

---

AI を活用した分析機能で、音楽コレクションをインテリジェントで検索可能なライブラリに変えましょう！ 🎶

要件

• Python 3.8+
• Docker（コンテナ化されたデプロイ用）

ライセンス

MIT License

Copyright (c) 2025 Music Collection MCP Server

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.