MuseScore MCP服务器
一种模型上下文协议（MCP）服务器，通过基于WebSocket的插件系统提供对MuseScore的编程控制。这允许像克劳德这样的人工智能助手创作音乐、添加歌词、导航乐谱，并直接控制MuseScore。
先决条件
- MuseScore 3.x或4.x
- Python 3.8+
- Claude Desktop或兼容的MCP客户端
设置
1.安装MuseScore插件
首先，将QML插件代码保存到您的MuseScore插件目录中：
macOS: ~/Documents/MuseScore4/Plugins/musescore-mcp-websocket.qml 视窗: %USERPROFILE%\Documents\MuseScore4\Plugins\musescore-mcp-websocket.qml Linux: ~/Documents/MuseScore4/Plugins/musescore-mcp-websocket.qml
2.在MuseScore中启用插件
- Open MuseScore
- 首选 插件→ 插件管理器
- 找到“MuseSore API服务器”并选中此框以启用它
- 点击 好的
3.设置Python环境
git clone
cd mcp-agents-demo
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
pip install fastmcp websockets4.配置克劳德桌面
添加到您的Claude Desktop配置文件中：
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"musescore": {
"command": "/path/to/your/project/.venv/bin/python",
"args": [
"/path/to/your/project/server.py"
]
}
}
}备注：更新路径以匹配您的实际项目位置。
运行系统
运算顺序
- 首先启动MuseScore 比分未定
- 运行MuseScore插件首选 插件→ MuseScore API服务器
- 您应该看到控制台输出： "Starting MuseScore API Server on port 8765"
- 然后启动Python MCP服务器 或重新启动克劳德桌面
\[插入不同功能、协调、夸张写作的屏幕截图，放大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视窗:
cd "C:\Program Files\MuseScore 4\bin"
MuseScore.exeLinux:
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)-用于提取交叉测量、多员工措辞的切片工具
Polyphony和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)明星历史
故障排除
连接问题
- “未连接到MuseScore”:
- 确保MuseScore在分数打开的情况下运行 - 运行MuseScore插件（插件→ MuseSore API服务器） - 检查端口8765是否未被防火墙阻止
插件问题
- 插件未出现：检查
.qml文件位于正确的插件目录中 - 插件无法启用：放置插件文件后重新启动MuseScore
- 无控制台输出：从终端运行MuseScore以查看调试消息
Python服务器问题
- “找不到服务器对象”：服务器对象必须命名
mcp,server，或app在模块级别 - WebSocket错误：在启动Python服务器之前，请确保MuseScore插件正在运行
- 连接超时：MuseScore插件必须处于活动状态，而不仅仅是启用状态
API限制
- 歌词：MuseSore 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 definitionsMIDI音高参考
供参考的常见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}