MuseScore MCP 服务器

一个模型上下文协议 (MCP) 服务器，通过基于 WebSocket 的插件系统提供对 MuseScore 的程序化控制。这允许像 Claude 这样的 AI 助手直接创作音乐、添加歌词、导航乐谱并控制 MuseScore。

先决条件

• MuseScore 3.x 或 4.x

• Python 3.8+

• Claude Desktop 或兼容的 MCP 客户端

Related MCP server: Ableton Copilot MCP

设置

1. 安装 MuseScore 插件

首先，将 QML 插件代码保存到您的 MuseScore 插件目录中：

macOS: ~/Documents/MuseScore4/Plugins/musescore-mcp-websocket.qml Windows: %USERPROFILE%\Documents\MuseScore4\Plugins\musescore-mcp-websocket.qml Linux: ~/Documents/MuseScore4/Plugins/musescore-mcp-websocket.qml

2. 在 MuseScore 中启用插件

1. 打开 MuseScore

2. 转到 插件 (Plugins) → 插件管理器 (Plugin Manager)

3. 找到“MuseScore API Server”并勾选复选框以启用它

4. 点击 确定 (OK)

3. 设置 Python 环境

git clone <your-repo>
cd mcp-agents-demo
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install fastmcp websockets

4. 配置 Claude Desktop

添加到您的 Claude Desktop 配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "musescore": {
      "command": "/path/to/your/project/.venv/bin/python",
      "args": [
        "/path/to/your/project/server.py"
      ]
    }
  }
}

注意：更新路径以匹配您的实际项目位置。

运行系统

操作顺序

1. 先启动 MuseScore 并打开一个乐谱

2. 运行 MuseScore 插件：转到 插件 (Plugins) → MuseScore API Server

   • 您应该会看到控制台输出："Starting MuseScore API Server on port 8765"

3. 然后启动 Python MCP 服务器 或重启 Claude Desktop

[插入不同功能、和声、旋律编写的截图，作为缩放的 GIF]

开发与测试

对于开发，请使用 MCP 开发工具：

# Install MCP dev tools
pip install mcp

# Test your server
mcp dev server.py

# Check connection status
mcp dev server.py --inspect

查看控制台输出

要查看 MuseScore 插件的控制台输出，请从终端运行 MuseScore：

macOS：

/Applications/MuseScore\ 4.app/Contents/MacOS/mscore

Windows：

cd "C:\Program Files\MuseScore 4\bin"
MuseScore.exe

Linux：

musescore4

功能

此 MCP 服务器提供全面的 MuseScore 控制。

🌟 此分支新增：内置自动、完美的复调多声部 & 映射到 LilyPond 的时间布局！

导航与光标控制

• get_cursor_info() - 获取当前光标位置和选择信息

• go_to_measure(measure) - 导航到特定小节

• go_to_beginning_of_score() / go_to_final_measure() - 导航到乐谱开头/结尾

• next_element() / prev_element() - 逐个元素移动光标

• next_staff() / prev_staff() - 在五线谱之间移动

• select_current_measure() - 选择当前整个小节

• select_custom_range(start_tick, end_tick, start_staff, end_staff) - 用于提取跨小节、多五线谱乐句的切片工具

复调 & LilyPond 集成

• 时间节奏填充：带有间隙或休止符的声部会自动接收 LilyPond 间隔序列 (s4.) 以准确保持其数学位置。

• 并发声部渲染：完整的 4 声部 (\voiceOne, \voiceTwo 等) 数组结构正确，并按五线谱分片，以便进行高级代理处理。

音符 & 休止符创建

• add_note(pitch, duration, advance_cursor_after_action) - 使用 MIDI 音高添加音符

• add_rest(duration, advance_cursor_after_action) - 添加休止符

• add_tuplet(duration, ratio, advance_cursor_after_action) - 添加连音符（三连音等）

小节管理

• insert_measure() - 在当前位置插入小节

• append_measure(count) - 在乐谱末尾添加小节

• delete_selection(measure) - 删除当前选择或特定小节

歌词 & 文本

• add_lyrics_to_current_note(text) - 为当前音符添加歌词

• add_lyrics(lyrics_list) - 批量为多个音符添加歌词

• set_title(title) - 设置乐谱标题

乐谱信息

• get_score() - 获取完整的乐谱分析和结构

• ping_musescore() - 测试与 MuseScore 的连接

• connect_to_musescore() - 建立 WebSocket 连接

实用工具

• undo() - 撤销上一步操作

• set_time_signature(numerator, denominator) - 更改拍号

• processSequence(sequence) - 批量执行多个命令

音乐示例

查看 /examples 文件夹以获取展示各种音乐风格的 MuseScore 示例文件：

• 亚洲器乐 - 传统的亚洲风格器乐曲

• 弦乐四重奏 - 古典弦乐四重奏编曲

每个示例包括：

• .mscz - MuseScore 文件（可编辑）

• .pdf - 乐谱

• .mp3 - 音频预览

使用示例

创建简单的旋律

# Set up the score
await set_title("My First Song")
await go_to_beginning_of_score()

# Add notes (MIDI pitch: 60=C, 62=D, 64=E, etc.)
await add_note(60, {"numerator": 1, "denominator": 4}, True)  # Quarter note C
await add_note(64, {"numerator": 1, "denominator": 4}, True)  # Quarter note E
await add_note(67, {"numerator": 1, "denominator": 4}, True)  # Quarter note G
await add_note(72, {"numerator": 1, "denominator": 2}, True)  # Half note C

# Add lyrics
await go_to_beginning_of_score()
await add_lyrics_to_current_note("Do")
await next_element()
await add_lyrics_to_current_note("Mi")
await next_element()
await add_lyrics_to_current_note("Sol")
await next_element()
await add_lyrics_to_current_note("Do")

批量操作

# Add multiple lyrics at once
await add_lyrics(["Twin-", "kle", "twin-", "kle", "lit-", "tle", "star"])

# Use sequence processing for complex operations
sequence = [
    {"action": "goToBeginningOfScore", "params": {}},
    {"action": "addNote", "params": {"pitch": 60, "duration": {"numerator": 1, "denominator": 4}, "advanceCursorAfterAction": True}},
    {"action": "addNote", "params": {"pitch": 64, "duration": {"numerator": 1, "denominator": 4}, "advanceCursorAfterAction": True}},
    {"action": "addRest", "params": {"duration": {"numerator": 1, "denominator": 4}, "advanceCursorAfterAction": True}}
]
await processSequence(sequence)

星标历史

故障排除

连接问题

• "Not connected to MuseScore"：

  • 确保 MuseScore 正在运行并打开了乐谱

  • 运行 MuseScore 插件 (Plugins → MuseScore API Server)

  • 检查 8765 端口是否未被防火墙阻止

插件问题

• 插件未显示：检查 .qml 文件是否在正确的插件目录中

• 插件无法启用：放置插件文件后重启 MuseScore

• 无控制台输出：从终端运行 MuseScore 以查看调试消息

Python 服务器问题

• "No server object found"：服务器对象必须在模块级别命名为 mcp、server 或 app

• WebSocket 错误：在启动 Python 服务器之前，确保 MuseScore 插件正在运行

• 连接超时：MuseScore 插件必须处于活动运行状态，而不仅仅是已启用

API 限制

• 歌词：MuseScore 3.x 插件 API 仅支持第一段歌词

• 标题设置：由于框架访问限制，使用了多种回退方法

• 选择持久性：某些操作可能会影响当前选择

文件结构

mcp-agents-demo/
├── .venv/
├── server.py                           # Python MCP server entry point
├── musescore-mcp-websocket.qml         # MuseScore plugin
├── requirements.txt
├── README.md
└── src/                                # Source code modules
    ├── __init__.py
    ├── client/                         # WebSocket client functionality
    │   ├── __init__.py
    │   └── websocket_client.py
    ├── tools/                          # MCP tool implementations
    │   ├── __init__.py
    │   ├── connection.py               # Connection management tools
    │   ├── navigation.py               # Score navigation tools
    │   ├── notes_measures.py           # Note and measure manipulation
    │   ├── sequences.py                # Batch operation tools
    │   ├── staff_instruments.py        # Staff and instrument tools
    │   └── time_tempo.py               # Timing and tempo tools
    └── types/                          # Type definitions
        ├── __init__.py
        └── action_types.py             # WebSocket action type definitions

MIDI 音高参考

常用的 MIDI 音高值参考：

• 中央 C: 60

• C 大调音阶: 60, 62, 64, 65, 67, 69, 71, 72

• 半音阶: C=60, C#=61, D=62, D#=63, E=64, F=65, F#=66, G=67, G#=68, A=69, A#=70, B=71

时值参考

时值格式: {"numerator": int, "denominator": int}

• 全音符: {"numerator": 1, "denominator": 1}

• 二分音符: {"numerator": 1, "denominator": 2}

• 四分音符: {"numerator": 1, "denominator": 4}

• 八分音符: {"numerator": 1, "denominator": 8}

• 附点四分音符: {"numerator": 3, "denominator": 8}