MusicXML to ABC

musicxml-abc-mcp

可在 MusicXML 与 ABC 记谱法之间转换的 MCP 服务。

功能

连接 MusicXML（标准但冗长的 XML 格式）与 ABC 记谱法（简洁、易读的文本格式）。主要用途是支持借助大模型编辑乐谱：MusicXML → ABC → Claude 编辑 → ABC → MusicXML。

ABC 很适合由大模型编辑，因为它足够简洁，可以放入上下文窗口，同时表达能力足以表示大多数合唱音乐。

工具

工具	描述
musicxml_to_abc	将 MusicXML（musicxml 文本或 musicxml_path）转换为 ABC 记谱法；也可以筛选单个声部和一段印刷小节（measures）
abc_to_musicxml	将 ABC 记谱法转换回 MusicXML；大型乐谱会写入文件（return：auto / path / inline）
validate_abc	解析 ABC 字符串并返回错误或警告
list_capabilities	返回服务元数据：后端版本、ABC 标准
health_check	执行 MusicXML → ABC → MusicXML 往返冒烟测试并报告状态
describe_score	简要总结乐谱：声部（ID P1…）、调性、拍号、速度、音域、小节

安装

cd musicxml-abc-mcp
uv sync --extra dev

注意：安装 pytest 时使用 --extra dev（而非 --group dev）。

如需按引导完成设置（若需要则安装 uv，然后同步依赖），请运行 ./install.sh — 分步说明见 SETUP.md。现成的客户端配置（Claude Desktop、Cursor、Windsurf、Continue、Zed）位于 examples/。如果遇到问题， 请查看 TROUBLESHOOTING.md。

运行

uv run musicxml-abc-mcp

无需环境变量。可选：SHEET_MUSIC_OUTPUT_ROOT（大型乐谱的写入位置和读取路径的位置；默认是工作目录）、SHEET_MUSIC_INPUT_ROOTS（用于读取乐谱的额外文件夹）以及 SHEET_MUSIC_INLINE_MAX_BYTES（默认 8192）。参见 Score References。

使用示例

乐谱可以作为文本（musicxml）传入，也可以通过文件路径传入（musicxml_path：允许的文件夹内的 .musicxml、.xml 或 .mxl 文件）。abc_to_musicxml 会将小型乐谱作为文本返回，并将大型乐谱写入 <output root>/scores/，返回 musicxml_path 和简短的 score_summary； 传入 "return": "inline" 可始终获取文本。

// Convert full score to ABC
{
  "tool": "musicxml_to_abc",
  "arguments": {"musicxml": "<score-partwise>...</score-partwise>"}
}
// → {"abc": "X:1\nT:...\n...", "parts_included": ["P1", "P2", "P3", "P4"], "warnings": []}

// Extract just the Soprano part
{
  "tool": "musicxml_to_abc",
  "arguments": {"musicxml": "<score-partwise>...</score-partwise>", "part": "Soprano"}
}
// `part` takes a part ID ("P1"), name ("soprano", any case) or voice ("S"); an unknown part
// returns the valid choices. `part_id` is a deprecated alias for one minor release.

// Just bars 17–24 of the Alto part
{
  "tool": "musicxml_to_abc",
  "arguments": {"musicxml_path": "scores/anthem.musicxml", "part": "Alto", "measures": [17, 24]}
}
// `measures` are the printed bar numbers, inclusive (a pickup bar is 0). The ABC headers (K:, M:,
// Q:) are the key, time and tempo in force at bar 17. A range outside the score returns
// INVALID_PARAMETER with a hint such as "This score has measures 1–32."

// Convert edited ABC back to MusicXML
{
  "tool": "abc_to_musicxml",
  "arguments": {"abc": "X:1\nT:My Song\n..."}
}
// → {"musicxml": "<?xml version=\"1.0\"?>...", "warnings": []}

// Validate ABC before converting
{
  "tool": "validate_abc",
  "arguments": {"abc": "X:1\nT:My Song\n..."}
}

ABC 记谱法基础

此服务使用 ABC 标准 v2.1：

• C（大写）= C4（中央 C）
• c（小写）= C5（比中央 C 高一个八度）
• 撇号表示升高一个八度：c' = C6
• 逗号表示降低一个八度：C, = C3

往返转换时音符的误差保持在 ±2% 以内。力度和复杂的演奏法不会保留。

测试

# All tests including integration (round-trip SATB conversion)
VIRTUAL_ENV= .venv/bin/pytest tests/ -v

依赖项

• music21 — 乐谱解析；ABC 输出使用自定义序列化器（music21 9.x 没有 ABC 写入器）
• mcp — MCP 协议

系统要求

• Python 3.11+
• 无需系统库