MuseScore MCP 服务器

这是一个基于Model Context Protocol (MCP)的服务器，通过基于WebSocket的插件系统对MuseScore进行编程控制。这使得像Claude这样的AI助手能够作曲、添加歌词、浏览乐谱并直接控制MuseScore。

预备条件

• MuseScore 3.x 或 4.x
• Python 3.8+
• Claude Desktop 或 兼容的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. 转到插件 → 插件管理器
3. 查找“MuseScore API Server”并勾选以启用它
4. 点击确定

3. 设置Python环境

git clone <your-repo>
cd mcp-agents-demo
python -m venv .venv
source .venv/bin/activate  # 在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插件：转到插件 → MuseScore API Server
   • 您应该看到控制台输出：“Starting MuseScore API Server on port 8765”
3. 然后启动Python MCP服务器 或重启Claude Desktop

[插入不同功能的截图，如和声、旋律写作等，作为放大版GIF]

开发与测试

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

# 安装MCP开发工具
pip install mcp

# 测试您的服务器
mcp dev server.py

# 检查连接状态
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控制：

导航及光标控制

• 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() - 选择当前小节

音符与休止符创建

• 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 - 音频预览

使用示例

创建简单旋律

# 设置乐谱
await set_title("我的第一首歌")
await go_to_beginning_of_score()

# 添加音符（MIDI音高：60=C, 62=D, 64=E等）
await add_note(60, {"numerator": 1, "denominator": 4}, True)  # 四分音符C
await add_note(64, {"numerator": 1, "denominator": 4}, True)  # 四分音符E
await add_note(67, {"numerator": 1, "denominator": 4}, True)  # 四分音符G
await add_note(72, {"numerator": 1, "denominator": 2}, True)  # 二分音符C

# 添加歌词
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")

批量操作

# 一次添加多条歌词
await add_lyrics(["双-", "胞", "双-", "胞", "小-", "星星"])
# 使用序列处理进行复杂操作
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)

故障排除

连接问题

• "未连接到MuseScore"：
  • 确保MuseScore正在运行且已打开乐谱
  • 运行MuseScore插件（插件 → MuseScore API Server）
  • 检查端口8765是否未被防火墙阻止

插件问题

• 插件未出现：检查.qml文件是否位于正确的插件目录中
• 插件无法启用：放置插件文件后重新启动MuseScore
• 无控制台输出：从终端运行MuseScore以查看调试消息

Python服务器问题

• "未找到服务器对象"：服务器对象必须在模块级别命名为mcp、server或app
• WebSocket错误：确保在启动Python服务器之前MuseScore插件正在运行
• 连接超时：MuseScore插件必须积极运行，而不仅仅是启用

API限制

• 歌词：MuseScore 3.x插件API仅支持第一段歌词
• 标题设置：由于框架访问限制，使用多种备用方法
• 选择持久性：某些操作可能会影响当前选择

文件结构

mcp-agents-demo/
├── .venv/
├── server.py                           # Python MCP服务器入口点
├── musescore-mcp-websocket.qml         # MuseScore插件
├── requirements.txt
├── README.md
└── src/                                # 源代码模块
    ├── __init__.py
    ├── client/                         # WebSocket客户端功能
    │   ├── __init__.py
    │   └── websocket_client.py
    ├── tools/                          # MCP工具实现
    │   ├── __init__.py
    │   ├── connection.py               # 连接管理工具
    │   ├── navigation.py               # 乐谱导航工具
    │   ├── notes_measures.py           # 音符和小节操作
    │   ├── sequences.py                # 批量操作工具
    │   ├── staff_instruments.py        # 五线谱和乐器工具
    │   └── time_tempo.py               # 时间和节奏工具
    └── types/                          # 类型定义
        ├── __init__.py
        └── action_types.py             # WebSocket动作类型定义

要求

创建一个requirements.txt文件，包含：

fastmcp
websockets

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}