Skip to main content
Glama
README.md
# EasyMuseMCP

**用一句话(或一次工具调用)直接写出真正的 MuseScore 乐谱。**

EasyMuseMCP 把「紧凑的文本记谱」编译成 MusicXML,再驱动 MuseScore 的命令行(无窗口)导出 `.mscz / .pdf / .png / .svg / .midi / .mp3`。它同时提供两个入口:

- **CLI(`msc`)** —— 人和脚本都能用
- **MCP server** —— 让 Claude / Cursor / DSH 等 AI 客户端把它当成内置工具调用

不需要打开 MuseScore 窗口,不需要装 QML 插件,不需要 WebSocket。纯 Node.js,零第三方依赖。

![钢琴谱示例](docs/demo-moonlight.png)

---

## 目录

- [为什么做这个](#为什么做这个)
- [工作原理](#工作原理)
- [环境要求](#环境要求)
- [安装](#安装)
- [快速开始(CLI)](#快速开始cli)
- [接入 MCP 客户端](#接入-mcp-客户端)
- [MCP 工具清单](#mcp-工具清单)
- [记谱语法](#记谱语法)
- [编辑已有乐谱](#编辑已有乐谱)
- [CLI 全部命令](#cli-全部命令)
- [实现要点(踩过的坑)](#实现要点踩过的坑)
- [已知限制](#已知限制)
- [项目结构](#项目结构)
- [开发与测试](#开发与测试)
- [许可](#许可)

---

## 为什么做这个

社区里已有的 MuseScore MCP(比如 `mcp-musescore` 一类)基本都走 **GUI + QML 插件 + WebSocket** 路线:必须让 MuseScore 窗口开着、手动进 Plugins 启用插件、靠移动光标一个个敲音符。

这条路子的问题很明显:不能批量、不能无人值守、出错就卡在光标位置、也没法在服务器上跑。

EasyMuseMCP 换了个底层:**MuseScore 自带的无窗口转换模式**才是一台真正的「渲染引擎」——你只要把 MusicXML 交给它,它就能排出一份正经乐谱。于是问题变成「怎么把人类/模型想写的音乐,可靠地变成 MusicXML」,剩下的都交给 MuseScore。

实测:单页钢琴谱从文本到 PDF/PNG/MIDI/MP3 约 2–6 秒。

---

## 工作原理

```
文本 DSL ──解析──> 乐谱模型 ──生成──> MusicXML ──MuseScore CLI──> mscz / pdf / png / midi / mp3
                      │                    ▲
                      ├─ 小节时值校验       │
                      ├─ 连音线/歌词/反复    └── 编辑层:改标题、速度、调号、移调、增删小节、加歌词
                      └─ 演奏法/装饰音/踏板
```

关键设计:

| 模块 | 作用 |
|---|---|
| `lib/dsl.js` | 解析文本记谱,做**小节时值校验**(不够补休止、超了报错并给出小节号) |
| `lib/musicxml.js` | 生成 MusicXML 4.0,处理调号、连音线、歌词、反复、装饰音、踏板、版面 |
| `lib/mscore.js` | 封装 MuseScore CLI:定位程序、导出、抽 JSON、收集产物 |
| `lib/edit.js` | 在 MusicXML 上做小节/元素级编辑,用于改**已有**乐谱 |
| `lib/transpose.js` | 纯文本移调,对任意 MuseScore 可读格式生效 |
| `server.js` | 零依赖 stdio MCP server(手写 JSON-RPC) |

---

## 环境要求

| 依赖 | 版本 | 说明 |
|---|---|---|
| Node.js | ≥ 18 | 用到了 ESM 与 `node:` 内置模块 |
| MuseScore | 3.x / 4.x | 提供无窗口渲染,**必须安装**(推荐 MuseScore 4) |

MuseScore 会被自动探测,常见路径:

- macOS:`/Applications/MuseScore 4.app/Contents/MacOS/mscore`
- Linux:`/usr/bin/mscore`、`/usr/local/bin/mscore`
- Windows:请把 `MSCORE_BIN` 设为 `MuseScore4.exe` 的完整路径

```bash
# 自检
node bin/msc.js doctor
# MuseScore binary : /Applications/MuseScore 4.app/Contents/MacOS/mscore
# version          : 4.7.4
# status           : ready
```

自定义路径:`export MSCORE_BIN=/path/to/mscore`

---

## 安装

```bash
git clone https://github.com/Ranger013/EasyMuseMCP.git
cd EasyMuseMCP
node bin/msc.js doctor
```

想全局使用 `msc` 命令:

```bash
npm link          # 之后可以直接敲 msc
```

或直接从仓库跑(无需安装):

```bash
npx github:Ranger013/EasyMuseMCP doctor
```

---

## 快速开始(CLI)

写一个 `song.msc`:

```text
title: 小星星
composer: 法国民谣
key: C
time: 4/4
tempo: 100

part "Piano" instrument=piano staves=2 clefs=treble,bass
voices 1
C5/4 C5/4 G5/4 G5/4 | A5/4 A5/4 G5/2 |
voices 2
C3/2 C3/2 | F2/2 C3/2 |
```

一条命令出全套:

```bash
node bin/msc.js compose song.msc --formats pdf,png,mscz,midi,mp3 --out out/song
```

```
✔ 小星星 — 2 measures, 12 notes, 1 part(s)
  musicxml out/song/song.musicxml
  mscz     out/song/song.mscz
  pdf      out/song/song.pdf
  png      out/song/song-1.png
  midi     out/song/song.midi
  mp3      out/song/song.mp3
```

其它常用命令:

```bash
msc ref                        # 打印完整记谱语法
msc inspect out/song/song.mscz  # 读标题/调号/拍号/速度/声部/页数/时长
msc transpose song.mscz --semitones -2
msc parts song.mscz            # 按声部导出分谱
msc open song.mscz             # 在 MuseScore 里打开继续手改
```

---

## 接入 MCP 客户端

server 走 **stdio**,所以配置里给一个启动命令即可。

**Claude Desktop / Claude Code / Cursor 等(JSON)**

```json
{
  "mcpServers": {
    "easymuse": {
      "command": "node",
      "args": ["/绝对路径/EasyMuseMCP/server.js"]
    }
  }
}
```

**DSH(`~/.dsh/profiles/<profile>/cordis.patch.yml`)**

```yaml
- insert:
    - name: "@deepseek-ai/dsh-mcp-client"
      config:
        transport: stdio
        serverName: musescore          # 工具前缀 → mcp__musescore__*
        command: /usr/local/bin/node
        args: ["/绝对路径/EasyMuseMCP/server.js"]
        toolCallTimeoutMs: 180000
        failOnStartupError: false
```

接入后模型会先调 `musescore_notation_reference` 读语法,然后用 `musescore_compose` 写谱、用 `musescore_view` 把渲染结果**当图片看**回来,自己检查排版。

---

## MCP 工具清单

共 11 个工具:

| 工具 | 用途 |
|---|---|
| `musescore_doctor` | 检查 MuseScore 是否可用、版本号 |
| `musescore_notation_reference` | 返回记谱语法速查表(模型先读这个) |
| `musescore_compose` | 文本 → 乐谱,返回产物路径 + 音乐摘要 + 警告 |
| `musescore_render` | 任意乐谱转格式 / 单页导出 / 套用 `.mss` 样式 |
| `musescore_view` | 渲染某页并**以图片返回**,用于自查排版 |
| `musescore_inspect` | 读取元数据 |
| `musescore_transpose` | 整谱移调 |
| `musescore_extract_parts` | 按声部导出分谱 |
| `musescore_edit` | 按操作列表修改已有乐谱(见下) |
| `musescore_join` | 多份乐谱首尾相接 |
| `musescore_open` | 在 MuseScore GUI 中打开 |

---

## 记谱语法

完整版:`msc ref`。下面是最常用的部分。

```text
title: 欢乐颂            subtitle: Ode to Joy
composer: 贝多芬         key: G          time: 4/4        tempo: 120
systems: 4               page: A4        margins: 15      scaling: 7

part "Piano" instrument=piano staves=2 clefs=treble,bass
voices 1
|: E4/4 E4/4 F4/4 G4/4 | G4/4 F4/4 E4/4 D4/4 :|
voices 2
%ped [C3 E3 G3]/1 | %ped-up [G2 B2 D3]/1 |
```

| 写法 | 含义 |
|---|---|
| `C5/4` | 音名+八度 `/` 时值(4=四分,2=二分,1=全音符,8=八分,16=十六分) |
| `F#4/8` `Bb3/2` `Cn4/4` | 升 / 降 / 还原 |
| `C5/4.` `C5/4..` | 附点 / 双附点 |
| `[C4 E4 G4]/4` | 和弦(空格或逗号分隔) |
| `r/4`、`R` | 休止符 / 整小节休止 |
| `C5/2~ C5/2` | 连音线(自动配对,可跨小节) |
| `(C5/4 D5/4)` | 圆滑线 |
| `T3{ C5/8 D5/8 E5/8 }` | 三连音(也支持 T5 / T7) |
| `gD5/16` | 倚音;`g[C5 E5]/16` 倚音和弦 |
| `C5/4%stacc,accent` | 演奏法:stacc / staccissimo / accent / tenuto / marcato / breath / upbow / downbow |
| `F#5/2%trill` | 装饰音:trill / mordent / inv-mordent / turn / inv-turn / tremolo |
| `G4/1%fermata` | 延长记号 |
| `C5/4!mf` | 力度:pp p mp mf f ff sf fp |
| `C5/4"一"` | 歌词(词尾 `-` 表示同词未完) |
| `%ped` `%ped-up` `%ped-change` | 延音踏板 |
| `%cresc` `%dim` `%wedge-stop` | 渐强 / 渐弱发夹 |
| `@time=3/4` `@key=Eb` `@tempo=120` | 中途变拍号 / 变调 / 变速 |
| `\|` `\|\|` `\|]` `\|:` `:\|` | 小节线 / 终止线 / 反复记号 |

版面指令:`page`(A4/A5/A3/letter/`210x297`)、`margins`(毫米,1/2/4 个数字)、`scaling`(每谱间毫米数,调大即整体放大)、`staff-distance`、`system-distance`、`systems`(每行小节数)、`style`(复用 MuseScore 导出的 `.mss`)。

> **小节必须填满**:不足会自动补休止并告警,超出会告警并指出小节号。这是最主要的自查手段。

---

## 编辑已有乐谱

`msc edit` / `musescore_edit` 支持 11 个操作,作用对象可以是任何 MuseScore 能打开的文件(`.mscz`、`.musicxml`、`.mid`、`.gp` …):

| 操作 | 参数 | 说明 |
|---|---|---|
| `set_metadata` | `title` `subtitle` `composer` `lyricist` | 改元数据,缺的会自动新建 |
| `set_tempo` | `tempo` `measure?` | 改速度(可指定从第几小节起) |
| `set_key` | `key` `measure?` | 改调号 |
| `set_time` | `time` `measure?` | 改拍号(只改拍号,不重排已有音符时值) |
| `transpose` | `semitones` `from?` `to?` | 按小节范围移调 |
| `delete_measures` | `from` `to` | 删小节并重编号 |
| `duplicate_measures` | `from` `to` `times?` | 复制乐段(自动剥掉谱号/拍号/速度等结构元素) |
| `append_measures` | `count` | 追加空小节 |
| `add_lyrics` | `text` `staff?` `verse?` `part?` | 按音符顺序填歌词 |
| `set_instrument` | `instrument` `part?` | 换乐器 |
| `set_systems` | `measures` | 重排每行小节数(0 = 交给 MuseScore) |

示例:

```bash
# 加速、改副标题、把前 4 小节复制一遍、再重排成每行 4 小节
msc edit song.mscz --ops '[
  {"op":"set_tempo","tempo":108},
  {"op":"set_metadata","subtitle":"加长版"},
  {"op":"duplicate_measures","from":1,"to":4},
  {"op":"set_systems","measures":4}
]'

msc join a.mscz b.mscz --name medley   # 两首接成一首
```

---

## CLI 全部命令

```
msc doctor                              环境自检
msc ref                                 记谱语法
msc compose <file.msc|-> [--formats a,b] [--out dir] [--name slug] [--res dpi] [--trim px] [--style x.mss]
msc render  <score>      [--formats a,b] [--out dir] [--page n] [--style x.mss]
msc inspect <score>                     元数据
msc transpose <score> --semitones N     移调
msc parts   <score>                     导出分谱
msc open    <score>                     用 MuseScore 打开

msc set     <score> [--title|--subtitle|--composer|--lyricist|--tempo|--key|--time] [--at-measure N]
msc cut     <score> --measures 5-8
msc dup     <score> --measures 1-4 [--times 2]
msc pad     <score> --count 4
msc lyrics  <score> --text "一 闪 一 闪" [--staff 1] [--verse 1] [--part 1]
msc instr   <score> --instrument violin [--part 1]
msc systems <score> --per-line 4
msc join    <a> <b> [...]
msc edit    <score> --ops '<JSON 数组>'
```

格式:`musicxml` `mscz` `pdf` `png` `svg` `midi` `mp3`。

---

## 实现要点(踩过的坑)

这些都是在真实 MuseScore 4.7 上撞出来的,写下来省得你再撞一遍:

1. **反复记号必须写进每个声部**。只要有一个声部缺反复小节线,MuseScore 会把整份谱的反复**静默丢弃**。所以反复提升到全谱级,每个 part 都发一遍。
2. **前反复要写在上一小节末尾**(`<barline location="right">` + `bar-style heavy-light`),写在下一小节开头会被忽略。
3. **标题必须用 `<credit>` + `<credit-type>`**。MuseScore 把 `movement-title` 当大标题,而普通 `<credit>` 会**顶掉**标题;只有带 `credit-type: title/subtitle` 才生成正确的两行。
4. **调号内的音不要画临时记号**。G 大调里的 F# 若照写 `<accidental>sharp</accidental>` 会多一个升号;要按五度圈判断,只在偏离调号时输出。
5. **变拍/变调不能顺带重打速度记号**——否则每个变换小节都会多印一个 `♩=`。
6. **复制小节要剥掉结构元素**:`<attributes>`、`<print>`、`<metronome>` 都在小节里,复制时不清理,谱中间会冒出多余的谱号/拍号/速度。
7. **往返后的 XML 标签带属性**:`<metronome parentheses="no">`、`<sound tempo="90" dynamics="..."/>`,正则必须容忍属性,否则编辑操作会静默失效。
8. **`-T 0` 裁剪不可靠**:裁剪边界可能比内容窄,把右侧音符切掉。默认整页导出。
9. **PNG/SVG 输出名带页码**:`-o x.png` 实际得到 `x-1.png`。
10. **`--score-parts` 不落盘**:各分谱以 base64 塞进 JSON 的 `partsBin` 打到 stdout。
11. **`--score-meta` 的 stdout 混着日志**,要从第一个 `{` 起做括号配平再 `JSON.parse`。
12. **退出码不可信**:MuseScore 有时写完文件后崩溃(macOS 上常见 `Abort trap: 6`)。判定成功以「产物存在且非空」为准。

---

## 已知限制

- 反复段落的**一二房(volta)**、琶音记号、滑音、自定义符头暂未支持。
- 中途变拍只改拍号,不会重排已有音符的时值。
- 编辑粒度是「小节 / 元素」,没有逐音符拖拽式编辑。
- 不支持在**已打开的 MuseScore 窗口里实时改谱**(那需要 GUI 插件 + WebSocket,是另一套架构)。
- 不提供音频转谱(不能听 MP3 扒谱)。

---

## 项目结构

```
EasyMuseMCP/
├── bin/msc.js            CLI 入口
├── server.js             MCP server(stdio,零依赖)
├── lib/
│   ├── frac.js           分数运算(时值不碰浮点)
│   ├── dsl.js            文本记谱解析 + 小节校验
│   ├── musicxml.js       乐谱模型 → MusicXML
│   ├── mscore.js         MuseScore CLI 封装
│   ├── ops.js            compose / render / inspect / transpose / edit / join
│   ├── edit.js           已有乐谱的编辑操作 + 拼接
│   ├── transpose.js      MusicXML 移调
│   └── reference.js      语法速查表
├── examples/             示例乐谱
├── styles/               示例 .mss 样式
├── docs/                 文档配图
└── test/run.js           37 项单元测试
```

---

## 开发与测试

```bash
node test/run.js        # 37 项单元测试,不需要 MuseScore
node bin/msc.js doctor  # 需要 MuseScore 的集成自检
node bin/msc.js compose examples/moonlight-full.msc --formats pdf,png
```

单元测试覆盖:分数运算、时值类型、DSL 解析(和弦/三连音/连音线/歌词/倚音/变拍变调)、小节校验、MusicXML 生成、调号临时记号、移调、以及编辑层的每个操作。

---

## 许可

[MIT](LICENSE) © 2026 Ranger013

---

> 本项目只做「排版与转换」,不附带任何曲谱内容。使用生成的乐谱时请自行确认版权。

TDQS

A3.8/5.0

Scored across 11 tools

Disambiguation5/5

Each tool targets a clearly distinct action or lifecycle stage: check, reference, compose, inspect, render, view, transpose, extract, edit, join, and open. The closest overlap is render vs. view, but their outputs and purposes are explicitly differentiated (general export vs. page image inspection).

Naming Consistency4/5

All tools share a consistent musescore_ prefix and are readable, mostly using verb-style names. A couple of tools are noun phrases (musescore_doctor, musescore_notation_reference), which is a minor deviation from the otherwise action-oriented pattern.

Tool Count5/5

The server exposes 11 well-scoped tools, comfortably within the ideal range. Each tool covers a meaningful part of the MuseScore workflow without obvious redundancy.

Completeness5/5

The toolset covers the full practical lifecycle: setup check, notation guidance, composition, inspection, rendering, visual checking, transposition, part extraction, editing, joining, and opening in the desktop app. No significant operational gap is apparent for the stated purpose.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues