使用说明

MusicMind MCP

V2.20 | 32工具 | 150次测试 | 自适应评分 | 音频分析 | 情绪过滤

一个MCP服务器，让Claude能够深入、智能地访问您的Apple Music帐户——不仅仅是CRUD操作，还有一个完整的品味理解引擎，可以分析收听模式，构建流派/艺术家/情绪档案，并生成真正个性化的推荐和播放列表。

运作原理

You → Claude → MusicMind MCP → Apple Music API
                    ↓
              SQLite Cache ← Taste Engine → Recommendations
                    ↓
           Audio Analysis (optional)

MusicMind作为MCP服务器位于Claude和Apple Music之间。它在本地缓存你的库和收听历史，构建一个多维的品味档案（流派向量、艺术家亲和力、音频偏好、时间模式），并使用该档案对新音乐进行评分和排名，从而产生真正反映你所听内容的推荐，而不仅仅是流行音乐。

推荐引擎是 自适应的：对歌曲进行反馈，它会随着时间的推移学习你的偏好，自动调整评分权重。

特性

图书馆和目录访问

浏览完整的Apple Music库，搜索目录，查找具有丰富元数据的歌曲/艺术家/专辑，查看图表和编辑类别。

口味分析

基于缓存数据构建的算法配置文件：

类型亲和向量 --按新旧程度和频率加权，并进行分级体裁扩展
艺术家亲和力得分 --图书馆存在+收听历史+评分
音频特性偏好 --无损、Atmos、空间音频
发布年份分布 --新版本与目录偏好
熟悉度评分 --香农熵衡量你的品味有多冒险

智能推荐

四种发现策略与MMR多样性选择相结合，均使用完整的区域流派名称并按流派重叠进行预过滤：

类似的艺术家爬行 --Apple Music艺术家图的1步遍历（紧密，无漂移）
流派邻近探索 --搜索你的热门地区流派，过滤出零重叠结果
编辑挖掘 --使用完整流派名称从编辑播放列表中提取歌曲
图表过滤 --带有强制流派重叠检查的流派过滤图表

自适应评分引擎

10个评分维度，权重从您的反馈中学习：

尺寸	重量	描述
类型匹配	35%	余弦相似性与区域流派优先级（全流派1.0，父流派0.3）
音频相似性	20%	音频特征向量上的余弦——节拍/风格很重要（如果可用）
新颖性	12%	高斯钟形曲线——奖励熟悉的流派，新的艺术家组合
新鲜度	10%	符合您的发布年份偏好
多样性	8%	MMR惩罚以避免回声室
艺术家亲和力	8%	你听这位艺术家的音乐有多少（如果流派不对，会受到惩罚）
稳定性	7%	冷却最近推荐的歌曲
交叉策略	奖金	找到同一首歌的每增加一个策略，奖金增加5%
情绪提升	奖金	情境过滤（锻炼、放松、专注、聚会、悲伤、开车）
分类	奖金	来自SoundAnalysis标签（macOS，可选）

音频分析（3层，优雅降级）

第1级 （始终可用）：仅元数据评分
第2层 （需要ffmpeg+librosa）：从30秒的预览中提取7维音频特征——节奏、能量、亮度、可跳舞性、声学、效价代理、节拍强度
第3层 （仅限macOS）：通过Swift CLI添加Apple SoundAnalysis分类标签

播放列表生成

用自然语言描述一种氛围，MusicMind会创建一个真正的Apple Music播放列表：

"underground drill tracks for a late night drive"
"chill atmospheric stuff for studying"
"high energy workout bangers"

先决条件

Python 3.11+
紫外线 --Python包管理器
Apple开发者帐户 带有MusicKit密钥(.p8 文件）
- 创建一个 developer.apple.com/account/resources/authkeys
- 启用“媒体服务（MusicKit）”功能

可选（用于音频分析）

ffmpeg --用于M4A/AAC解码(brew install ffmpeg)
librosa --通过安装 uv sync --extra audio
Swift 5.9+-用于声音分析CLI（仅限macOS）

快速开始

# Clone
git clone https://github.com/Cyberfilo/musicmind-mcp.git
cd musicmind-mcp

# Install
uv sync --all-extras

# Setup (one-time: enters your Apple credentials + OAuth)
uv run python -m musicmind.setup

# Connect to Claude (automatic)
./scripts/connect-claude.sh

或手动连接——请参阅手动集成在......下面

安装详细信息

1.安装依赖项

uv sync --all-extras

对于音频分析（第2层），还应安装ffmpeg：

brew install ffmpeg          # macOS
sudo apt-get install ffmpeg  # Linux
uv sync --extra audio        # Install librosa + soundfile

2.Apple Music授权

uv run python -m musicmind.setup

向导将：

问你的 苹果开发者团队ID （10个字符，来自developer.apple.com）
问你的 MusicKit密钥ID （10个字符，来自您创建的密钥）
询问 通往你的路 .p8 私钥文件
打开浏览器窗口 苹果音乐OAuth --单击“授权”授予访问权限
将所有内容保存到 ~/.config/musicmind/config.json （权限 600)

3.联系克劳德

运行自动安装脚本：

./scripts/connect-claude.sh

这可以检测您是否拥有Claude Desktop、Claude Code或两者兼而有之，并自动配置MCP服务器。

手动集成

克劳德桌面版

添加 ~/.config/claude/claude_desktop_config.json:

{
  "mcpServers": {
    "musicmind": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/musicmind-mcp", "python", "-m", "musicmind"]
    }
  }
}

然后重新启动Claude Desktop。

克劳德代码（CLI）

从任何项目目录：

claude mcp add musicmind -- uv run --directory /absolute/path/to/musicmind-mcp python -m musicmind

或添加到 .mcp.json 在您的项目中：

{
  "mcpServers": {
    "musicmind": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/musicmind-mcp", "python", "-m", "musicmind"]
    }
  }
}

验证

在克劳德，问： “检查MusicMind健康状况” --它应该显示服务器版本、身份验证状态和缓存统计信息。

工具（32）

图书馆浏览

工具	说明
`musicmind_library_songs`	浏览您的曲库歌曲（分页，带有流派元数据）
`musicmind_library_albums`	浏览您的图书馆相册
`musicmind_library_artists`	浏览您的库艺术家
`musicmind_library_playlists`	列出您的所有播放列表
`musicmind_playlist_tracks`	获取特定播放列表中的曲目
`musicmind_search_library`	在图书馆内搜索

目录搜索和查找

工具	说明
`musicmind_search`	搜索Apple Music目录
`musicmind_lookup_song`	包含元数据和关系的完整歌曲细节
`musicmind_lookup_artist`	艺人详情+热门歌曲+相似艺人
`musicmind_lookup_album`	专辑详情+曲目列表
`musicmind_charts`	热门排行榜（歌曲、专辑、播放列表），可按流派选择
`musicmind_activities`	情绪/活动类别（放松、锻炼、专注等）
`musicmind_genres`	您店面的完整流派列表

听力历史

工具	说明
`musicmind_recently_played`	最近的曲目（自动缓存以进行口味分析）
`musicmind_heavy_rotation`	您一直在大量收听的内容
`musicmind_apple_recommendations`	苹果自己的个性化选择

图书馆管理

工具	说明
`musicmind_create_playlist`	使用可选的初始曲目创建新的播放列表
`musicmind_add_to_playlist`	将曲目添加到现有播放列表
`musicmind_add_to_library`	将目录歌曲添加到曲库
`musicmind_rate_song`	喜欢、不喜欢或删除评级

味道分析

工具	说明
`musicmind_taste_profile`	构建并展示您的完整品味档案
`musicmind_taste_compare`	给一首歌与你的口味匹配的程度打分
`musicmind_listening_stats`	从缓存数据中聚合统计数据
`musicmind_why_this_song`	解释歌曲的每个维度的口味匹配
`musicmind_taste_deep`	一次通话中提供全面的口味简报（简介+近期+模式）

智能推荐

工具	说明
`musicmind_discover`	寻找带有可选情绪和策略选择的新歌
`musicmind_smart_playlist`	用自然语言创建基于氛围的播放列表
`musicmind_curate_playlist`	Claude担任DJ：将“艺术家-头衔”查询解析为ID+创建播放列表
`musicmind_feedback`	用拇指向上/向下反馈训练发动机
`musicmind_refresh_cache`	重新获取数据并重建口味档案

系统

工具	说明
`musicmind_health`	服务器状态、身份验证检查、缓存统计信息
`musicmind_help`	带有示例提示的完整工具指南

示例提示

连接后，在Claude中尝试以下操作：

"Show me my music taste profile"
"What have I been listening to lately?"
"Search for 'Kendrick Lamar' in my library"
"Find me 20 new songs — use the similar artists strategy"
"Discover chill music for studying"
"Create a playlist called 'Night Drive' with underground drill vibes"
"Why would I like this song?" (after looking up a song ID)
"Give thumbs up to song 1234567890" (after a recommendation)
"What are the top charts right now?"
"Compare my taste to this album's tracks"
"Fammi una playlist estiva tipo drill milanese" (uses curate_playlist for regional scenes)
"Give me a deep taste briefing" (uses taste_deep for max context)

建筑

src/musicmind/
├── server.py          # FastMCP server + lifespan (DB, auth, client init)
├── config.py          # Config from ~/.config/musicmind/config.json
├── auth.py            # ES256 JWT developer token + Music User Token
├── client.py          # Async Apple Music API client (25+ endpoints)
├── models.py          # Pydantic response models
├── tools/
│   ├── library.py     # 6 library browsing tools
│   ├── catalog.py     # 7 catalog search/lookup tools
│   ├── playback.py    # 3 listening history tools
│   ├── manage.py      # 4 library management tools
│   ├── taste.py       # 5 taste analysis tools (+ taste_deep)
│   └── recommend.py   # 5 recommendation tools (+ curate_playlist)
├── engine/
│   ├── profile.py     # Taste profile builder (genre vectors, artist affinity, temporal decay)
│   ├── similarity.py  # Song/artist/audio similarity scoring
│   ├── scorer.py      # 10-dimension candidate scoring with adaptive weights
│   ├── discovery.py   # 4 discovery strategies
│   ├── weights.py     # Adaptive weight optimizer (coordinate descent from feedback)
│   ├── mood.py        # 6 mood profiles with genre + audio feature ranges
│   ├── audio.py       # Audio feature extraction via librosa (Tier 2)
│   └── classifier.py  # SoundAnalysis integration via Swift CLI (Tier 3)
└── db/
    ├── schema.py      # 9 SQLAlchemy Core tables
    ├── manager.py     # Async DB lifecycle
    └── queries.py     # All query methods

发展

uv run pytest              # Run all 150 tests
uv run pytest -v           # Verbose output
uv run ruff check src/     # Lint
uv run ruff check src/ --fix  # Auto-fix lint issues

使用说明

MusicMind MCP

运作原理

特性

图书馆和目录访问

口味分析

智能推荐

自适应评分引擎

音频分析（3层，优雅降级）

播放列表生成

先决条件

可选（用于音频分析）

快速开始

安装详细信息

1.安装依赖项

2.Apple Music授权

3.联系克劳德

手动集成

克劳德桌面版

克劳德代码（CLI）

验证

工具（32）

图书馆浏览

目录搜索和查找

听力历史

图书馆管理

味道分析

智能推荐

系统

示例提示

建筑

发展

相关 MCP

Spotify音乐管理服务

Spotify播放列表管理服务

专辑生成器

Spotify MCP 服务器

Spotify MCP服务

音乐推荐服务