音乐21-MCP服务器

Name: 音乐21-MCP服务器
Author: brightlikethelight

作者：brightlikethelight5 星标更新：2025-10-29

安装使用来源：spider==github.com

项目介绍

Music21 分析 - 多接口音乐服务器

通过四种不同的接口进行专业音乐分析 - MCP服务器、HTTP API、命令行工具和Python库。基于强大的music21库构建，具有协议无关架构以实现最大可靠性。

🎯 为什么提供多种接口？

根据2025年的研究显示，MCP的成功率为40-50%，本项目提供了通往相同强大music21分析功能的多种途径：

📡 MCP服务器 - 用于Claude桌面集成（当其工作时）
🌐 HTTP API - 用于网络应用（可靠的备份）
💻 命令行工具 - 用于自动化（始终有效）
🐍 Python库 - 用于直接编程访问

🎵 核心音乐分析功能

分析工具（13种可用）

导入与导出：MusicXML、MIDI、ABC、Lilypond、music21语料库
调性分析：多种算法（Krumhansl、Aarden、Bellman-Budge）
和声分析：罗马数字、和弦进程、终止式检测
声部进行：平行进行检测、声部交叉分析
模式识别：旋律、节奏和和声模式

高级功能

和声化：巴赫合唱和爵士风格的和声化
对位法：生成五种对位法（1-5）
风格模仿：学习并生成作曲家风格的音乐
乐谱操作：转调、时间拉伸、配器

🚀 快速开始

安装

从PyPI安装（推荐）

# 安装包
pip install music21-mcp-server

# 启动服务
music21-mcp-server --mode mcp   # 对于Claude桌面
music21-mcp-server --mode http  # 在localhost:8000上的REST API
music21-mcp-server --mode cli   # 交互式CLI

从源代码安装

# 克隆仓库
git clone https://github.com/brightlikethelight/music21-mcp-server.git
cd music21-mcp-server

# 使用UV安装（推荐）
curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync

# 或使用pip
pip install -r requirements.txt

# 配置music21语料库
python -m music21.configure

使用 - 选择您的接口

🎯 显示所有可用接口

python -m music21_mcp.launcher

📡 MCP服务器（用于Claude桌面）

# 启动MCP服务器
python -m music21_mcp.launcher mcp

# 配置Claude桌面：
# ~/.config/claude-desktop/config.json
{
  "mcpServers": {
    "music21-analysis": {
      "command": "python",
      "args": ["-m", "music21_mcp.server_minimal"],
      "env": {
        "PYTHONPATH": "/path/to/music21-mcp-server/src"
      }
    }
  }
}

🌐 HTTP API服务器（用于网络应用）

# 启动HTTP API服务器
python -m music21_mcp.launcher http
# 打开：http://localhost:8000
# API文档：http://localhost:8000/docs

# 示例用法：
curl -X POST "http://localhost:8000/scores/import" \
  -H "Content-Type: application/json" \
  -d '{"score_id": "chorale", "source": "bach/bwv66.6", "source_type": "corpus"}'

curl -X POST "http://localhost:8000/analysis/key" \
  -H "Content-Type: application/json" \
  -d '{"score_id": "chorale"}'

💻 命令行工具（用于自动化）

# 显示CLI状态
python -m music21_mcp.launcher cli status

# 导入并分析一个巴赫合唱
python -m music21_mcp.launcher cli import chorale bach/bwv66.6 corpus
python -m music21_mcp.launcher cli key-analysis chorale
python -m music21_mcp.launcher cli harmony chorale roman

# 列出所有工具
python -m music21_mcp.launcher cli tools

🐍 Python库（用于编程）

from music21_mcp.adapters import create_sync_analyzer

# 创建分析器
analyzer = create_sync_analyzer()

# 导入并分析
analyzer.import_score("chorale", "bach/bwv66.6", "corpus")
key_result = analyzer.analyze_key("chorale")
harmony_result = analyzer.analyze_harmony("chorale", "roman")

print(f"调性：{key_result}")
print(f"和声：{harmony_result}")

# 快速综合分析
analysis = analyzer.quick_analysis("chorale")

🧪 测试与开发

运行测试

# 现实测试套件（核心95%，适配器5%）
python tests/run_reality_tests.py

# 核心music21测试（必须通过）
python -m pytest tests/core/ -v

# MCP适配器测试（可能失败 - 这是预期的）
python -m pytest tests/adapters/ -v

开发设置

# 安装开发依赖
uv sync --dev

# 设置预提交钩子
pre-commit install

# 运行代码检查
ruff check src/
ruff format src/

# 类型检查
mypy src/

🏗️ 架构

协议无关设计

核心价值层：
├── services.py              # Music21分析服务（协议无关）
└── tools/                   # 13个音乐分析工具

协议适配层：
├── adapters/mcp_adapter.py   # MCP协议隔离
├── adapters/http_adapter.py  # HTTP/REST API
├── adapters/cli_adapter.py   # 命令行界面  
└── adapters/python_adapter.py # 直接Python访问

统一入口点：
└── launcher.py              # 所有接口的单一入口点

设计理念

核心价值优先：将Music21分析与协议问题隔离开来
协议末日生存：即使MCP失败也能工作（30-40%的时间）
多重逃生舱：始终有一个工作的接口
现实导向：为今天的MCP生态系统而建，而非企业梦想

📊 接口可靠性

接口	成功率	最适合
MCP	40-50%	AI助手集成
HTTP	95%+	网络应用
CLI	99%+	自动化及脚本
Python	99%+	直接编程

📚 文档

INTERFACES.md - 包含示例的完整接口指南
SIMPLIFIED.md - 架构简化理由
examples/ - 工作代码示例
API文档：http://localhost:8000/docs（当HTTP服务器运行时）

🔧 配置

环境变量

# 可选配置
export MUSIC21_MCP_LOG_LEVEL=INFO
export MUSIC21_MCP_CACHE_SIZE=100
export MUSIC21_MCP_TIMEOUT=30

Music21设置

# 配置语料库路径（一次性设置）
python -m music21.configure

🛠️ 可用分析工具

import_score - 从语料库、文件或URL导入
list_scores - 列出所有已导入的乐谱
get_score_info - 获取详细乐谱信息
export_score - 导出到MIDI、MusicXML等
delete_score - 从存储中删除乐谱
analyze_key - 调号分析
analyze_chords - 和弦进程分析
analyze_harmony - 罗马数字/功能性和声
analyze_voice_leading - 声部进行质量分析
recognize_patterns - 旋律/节奏模式识别
harmonize_melody - 自动和声化
generate_counterpoint - 对位法生成
imitate_style - 风格模仿与生成

🚀 快速示例

分析一个巴赫合唱

# CLI方法
python -m music21_mcp.launcher cli import chorale bach/bwv66.6 corpus
python -m music21_mcp.launcher cli key-analysis chorale

# Python方法  
analyzer = create_sync_analyzer()
analyzer.import_score("chorale", "bach/bwv66.6", "corpus")
print(analyzer.analyze_key("chorale"))

启动服务

# 对于Claude桌面
python -m music21_mcp.launcher mcp

# 对于网络开发
python -m music21_mcp.launcher http

# 对于命令行工作
python -m music21_mcp.launcher cli status

🔄 从v1.0迁移

之前的商业版本已被简化以提高可靠性：

✅ 保留：所有music21分析功能
✅ 添加：HTTP API、CLI、Python库接口
❌ 移除：Docker、K8s、复杂的认证、监控（对于MCP生态系统来说太不稳定）
🔄 更改：通过多种接口专注于核心价值交付

🤝 贡献

分叉仓库
创建功能分支：git checkout -b feature/amazing-feature
运行测试：python tests/run_reality_tests.py
提交更改：git commit -m '添加惊人的功能'
推送分支：git push origin feature/amazing-feature
提交拉取请求

📄 许可证

MIT许可证 - 详情见LICENSE文件。

🙏 致谢

基于优秀的music21库
使用FastMCP支持MCP协议
受到需要可靠音乐分析工具的需求启发

选择适合您的接口。所有接口都提供相同强大的music21分析能力！ 🎵