音乐库MCP服务器
一个模型上下文协议（MCP）服务器，提供对音乐库数据库的智能访问。通过AI助手（如Claude Desktop和Cursor）查询歌曲、探索艺术家、获取歌词并生成播放列表。
特点/功能
这个MCP服务器实现了所有三种MCP原语：
资源（可查询数据端点）
songs://schema- 数据模式文档 解释字段含义（⚠️请先阅读此内容！)songs://list- 浏览所有歌曲并分页显示songs://artist/{name}- 获取特定艺术家的所有歌曲songs://composer/{name}- 获取特定作曲家的所有歌曲songs://lyricist/{name}- 获取特定词作家的所有歌曲songs://translator/{name}- 获取特定翻译者的所有歌曲songs://collaboration/{lyricist}/{composer}- 从特定的创作合作中获取歌曲songs://category/{id}- 获取某一类别下的所有歌曲songs://categories- 列出所有可用的类别songs://artists- 列出所有艺术家及其歌曲数量songs://composers- 列出所有作曲家及其歌曲数量songs://lyricists- 列出所有作词人及其歌曲数量songs://translators- 列出所有翻译者及其翻译的歌曲数量songs://collaborations- 列出所有作词作曲人的合作作品songs://song/{id}- 获取单首歌曲的详细信息songs://stats- 数据库统计信息和见解
工具（搜索与数据操作）
search_songs- 通过名称、艺术家、类别、作曲家、作词家或翻译者进行模糊搜索get_lyrics- 从URL获取歌词内容get_youtube_metadata- 获取YouTube视频信息get_collaborations- 查询词曲作者合作，应用筛选条件
提示（引导式工作流）
explore_artist- 深入探索一位艺术家的唱片目录explore_contributor- 探索作曲家、作词家或翻译家的作品analyze_collaboration- 探索词曲创作者之间的创意合作create_playlist- 按主题生成精选播放列表discover_similar- 找出与给定歌曲相似的歌曲
重要数据说明
⚠️ 日期字段为内部时间戳
关键的；严重的该 dateCreated 并且 dateModified 歌曲数据中的字段是 内部数据库时间戳这些时间戳并非实际的歌曲创作或发布日期。它们表示的是数据库系统中条目被添加或修改的时间，而非歌曲本身创作的时间。
MCP服务器包含全面的 模式文档 在 songs://schema 人工智能客户端应阅读以理解所有字段的含义。这可以防止将内部元数据错误地解释为与音乐相关的信息。
这意味着：
- ❌ 不要使用这些字段来分析音乐史或时代
- ❌ 不要用这些字段来寻找“新”歌曲或发行作品
- ✅ 使用
newSongIds数组以查找最近添加的歌曲 - ✅ 使用类别和创作者字段进行音乐分析
安装
先决条件
- Python 3.10 或更高版本
- 该
songs.json文件在（某个地方/文件夹中）songs/目录
设置
- 以开发模式安装该包：
pip install -e .或者手动安装依赖项：
pip install mcp httpx- 验证安装：
python -m music_library_mcp.server配置
对于Claude Desktop
将此配置添加到您的Claude桌面配置文件中：
macOS（苹果电脑操作系统）： ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"music-library": {
"command": "python",
"args": [
"-m",
"music_library_mcp.server"
],
"cwd": "/Users/alonc/mcp-intro"
}
}
}确保更新 cwd 路径需与您实际的项目目录相匹配。
对于Cursor
将此添加到您的 Cursor 设置中（设置 > 功能 > MCP）：
{
"mcpServers": {
"music-library": {
"command": "python",
"args": [
"-m",
"music_library_mcp.server"
],
"cwd": "/Users/alonc/mcp-intro"
}
}
}对于其他MCP客户端
任何兼容MCP的客户端都可以使用stdio传输方式连接到此服务器。使用命令：
python -m music_library_mcp.server使用示例
配置完成后，您可以通过您的AI助手与音乐库进行互动：
探索艺术家
"Show me all songs by ������ ����"助手将使用 songs://artist/������ ���� 获取数据的资源。
搜索歌曲
"Find all Hebrew songs about dreams"助手将使用 search_songs 带有适当参数的工具。
创建播放列表
"Create an upbeat playlist with 10 Hebrew songs"助手将使用 create_playlist 提示以生成建议。
获取歌词
"Get the lyrics for song ID 1000001"助手将使用 get_lyrics 从URL获取歌词的工具。
寻找相似歌曲
"Find songs similar to �� �� ����"助手将首先搜索这首歌，然后使用 discover_similar 提示。
项目结构
mcp-intro/
�� music_library_mcp/
�� __init__.py # Package initialization
�� database.py # Core data layer with indexing
�� server.py # MCP server implementation
�� songs/
�� songs.json # Music library database
�� pyproject.toml # Package configuration
�� README.md # This file数据库模式
这个（或“该”） songs.json 文件包含：
{
"version": "2025_10_04",
"title": "Default Songs List new",
"categories": [
{
"id": "1",
"name": "Hebrew"
}
],
"songs": [
{
"id": 1000001,
"name": "�� �� ����",
"singer": "������ ����",
"playback": {
"youTubeVideoId": "LUpJ7L6xCoE"
},
"categoryIds": ["1"],
"lyrics": {
"markupUrl": "https://..."
},
"dateCreated": 1551830400000,
"dateModified": 1551830400000
}
]
}发展
本地测试
您可以使用MCP检查器测试服务器，或者直接运行服务器进行测试：
# Using the start script (recommended)
./scripts/start_server.sh
# Or manually
source .venv/bin/activate
python -m music_library_mcp.server
# Test the setup
./scripts/test_setup.sh添加新功能
该服务器设计便于扩展：
- 新资源在……中添加处理程序
@app.read_resource()函数 - 新工具添加到
@app.list_tools()并且@app.call_tool() - 新提示添加到
@app.list_prompts()和@app.get_prompt()
故障排除
服务器未出现在Claude桌面端
- 检查配置文件路径是否正确
- 验证
cwd路径指向你的项目目录 - 完全重启Claude桌面版
- 检查Claude桌面版的日志以查找错误
未找到Python模块
确保您已安装该软件包：
pip install -e .或者确保已安装MCP SDK：
pip install mcp httpx歌曲无法加载
验证 songs.json 文件是否存在于 songs/songs.json 相对于项目根目录。
许可证
麻省理工学院（MIT）
做出贡献
这是一个演示用的MCP服务器。您可以随意对其进行分叉（即复制并进行修改）和扩展，以满足您自己的使用需求。