Local Music Collection Mcp

音乐收藏 MCP 服务

功能强大的模型上下文协议（MCP）服务，可通过高级元数据管理、专辑类型分类和全面的数据分析，智能访问本地音乐收藏。

✨ 主要功能

• 🎵 智能音乐发现：智能扫描，支持 8 种专辑类型分类（专辑、EP、现场专辑、Demo、合辑、单曲、器乐专辑、Split）
• 📊 高级数据分析：收藏成熟度评估、健康评分和个性化推荐
• 🏗️ 灵活整理：支持多种文件夹结构，提供自动迁移和合规性评分
• ⚡ 高性能：优化扫描速度（快 20-30%）、批量操作和智能缓存
• 🤖 AI 集成：与 Claude Desktop 和其他 MCP 客户端无缝协作
• 🔄 自动设置：一条命令即可安装并生成配置

🚀 快速开始

选项 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)

📚 文档

快速上手

• 快速入门指南 - 几分钟内即可运行
• 安装指南 - 详细的设置说明
• 配置指南 - 高级配置选项

了解更多

• 使用示例 - 实际使用示例
• 收藏整理 - 最佳实践
• 专辑处理 - 了解专辑类型

获取帮助

• 常见问题 - 常见问题解答
• 故障排除 - 问题解决方法
• 评分系统 - 了解评分和分析

🔧 维护与脚本

script/ 目录提供了强大的维护工具：

• 安装：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%
• 分离的架构：将本地专辑与缺失专辑分开，便于管理
• 自动安装：通过一条命令完成安装和配置
• 专辑类型：智能的 8 种类型分类系统
• 灵活的结构：支持多种组织模式

🆘 需要帮助？

1. 查看常见问题，了解常见问题的解答
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 许可证

版权所有 (c) 2025 Music Collection MCP Server

特此免费授予任何获得本软件及相关文档文件（以下简称“软件”）副本的人不受限制地处理本软件的权利，包括但不限于使用、复制、修改、合并、发布、分发、再许可和／或销售本软件副本，以及允许获得本软件的人这样做，但须符合以下条件：

上述版权声明和本许可声明应包含在本软件的所有副本或重要部分中。

本软件按“原样”提供，不提供任何形式的明示或默示保证，包括但不限于适销性、特定用途适用性和非侵权的保证。在任何情况下，作者或版权持有人均不对因本软件、软件的使用或其他交易而引起的任何索赔、损害或其他责任承担责任，无论是合同、侵权或其他行为。