MIDI生成MCP

用于AI集成MIDI生成的MCP服务器

一种模型上下文协议（MCP）服务器，为人工智能辅助音乐创作提供低级MIDI操作工具。该服务器为MIDI生成提供确定性CRUD操作，将所有创造性推理保留在LLM（Claude）中。

特性

19个MCP工具 用于MIDI操作（包括和声和验证工具）
和弦进程跟踪 具有自动和声验证功能
表达式语法 为了精确计时（例如。， "9 + 1/3" 三胞胎）
通用MIDI支持 （128个仪器映射）
多轨MIDI导出 具有自动频道分配功能
取消/重做 （最多10个动作）
分段结构 每节有节奏/时间特征/关键
基于节拍的计时 （季度笔记，时间签名无关）

安装

先决条件

安装紫外线（推荐）：

curl -LsSf https://astral.sh/uv/install.sh | sh

来源

# Clone the repository
git clone https://github.com/IrisMu01/midi-gen-mcp.git
cd midi-gen-mcp

# Install with uv (recommended)
uv sync --all-extras

# Or use pip (legacy)
pip install -e ".[dev]"

快速设置

make install    # Install with dev dependencies (uses uv)
make test       # Run all tests (uses uv)

用法

运行MCP服务器

服务器通过stdio进行通信，该stdio专为与Claude Desktop或其他MCP客户端一起使用而设计。

# Run with uv (recommended)
uv run midi-gen-mcp

# Or with uv run python
uv run python -m midi_gen_mcp.server

# Legacy methods (if installed globally)
midi-gen-mcp
python -m midi_gen_mcp.server

为Claude桌面配置

添加到您的Claude Desktop MCP设置(claude_desktop_config.json):

使用紫外线（推荐）：

{
  "mcpServers": {
    "midi-gen": {
      "command": "uv",
      "args": ["--directory", "/path/to/midi-gen-mcp", "run", "midi-gen-mcp"]
    }
  }
}

使用直接命令：

{
  "mcpServers": {
    "midi-gen": {
      "command": "midi-gen-mcp"
    }
  }
}

使用Python路径：

{
  "mcpServers": {
    "midi-gen": {
      "command": "python",
      "args": ["-m", "midi_gen_mcp.server"]
    }
  }
}

MCP工具参考

歌曲管理

`set_title`

设定乐曲的标题。

参数：

title （string）：作品的标题

例子：

{
  "title": "Moonlight Sonata"
}

`get_piece_info`

获取当前作品的概述信息。

退货：

标题
章节概述
曲目列表
钞票总数

______________________________________________________________________

结构管理

`add_section`

在乐曲中添加一个新的部分，包括节奏、时间特征和基调。

参数：

name （string）：节名称（必须唯一）
start_measure （int）：起始度量（1-索引，≥1）
end_measure （int）：结束度量（含，≥start_measure）
tempo （int）：BPM中的时间（1-300）
time_signature （字符串）：时间签名（例如，“4/4”、“6/8”）
key （string）：密钥签名（例如，“C”、“Am”、“F#m”）
description （字符串，可选）：章节描述/注释

例子：

{
  "name": "intro",
  "start_measure": 1,
  "end_measure": 4,
  "tempo": 72,
  "time_signature": "4/4",
  "key": "Dm",
  "description": "Sparse piano, melancholic mood"
}

`edit_section`

编辑现有部分。自动调整相邻部分以防止重叠。

参数：

name （string）：要编辑的节的名称
start_measure （int，可选）：新的起始度量值
end_measure （int，可选）：新的结束度量值
tempo （int，可选）：BPM的新节奏
time_signature （字符串，可选）：新时间签名
key （字符串，可选）：新密钥签名
description （字符串，可选）：新描述

`get_sections`

获取工件中的所有部分，按start_measure排序。

______________________________________________________________________

跟踪管理

`add_track`

为乐曲添加新曲目。

参数：

name （string）：曲目名称（必须唯一）
instrument （string）：乐器名称（见下面的通用MIDI映射）

例子：

{
  "name": "piano",
  "instrument": "acoustic_grand_piano"
}

`remove_track`

删除曲目及其所有注释。

参数：

name （string）：要删除的曲目名称

`get_tracks`

把所有的痕迹都拼凑起来。

______________________________________________________________________

注释操作

`add_notes`

在工件上添加多个注释（批量操作）。

参数：

notes （array）：注释对象列表，包括：

- track （string）：曲目名称（必须存在） - pitch （int）：MIDI音符编号（0-127，其中60=中间C） - start （数字或字符串）：开始时间（节拍）（四分之一音符） - duration （数字或字符串）：持续时间（节拍）

表达式语法： 两者 start 和 duration 支持精确计时的数学表达式：

"1/3" -三联八分音符
"9 + 1/3" -击败9加1三连冠
"2 * 3" -6拍
简单数字： 0, 1.5, 4

例子：

{
  "notes": [
    {"track": "piano", "pitch": 60, "start": 0, "duration": 1},
    {"track": "piano", "pitch": 64, "start": "1 + 1/3", "duration": "1/3"},
    {"track": "violin", "pitch": 67, "start": 2, "duration": "1/2"}
  ]
}

`remove_notes_in_range`

删除某个时间范围内曲目中的所有音符。

参数：

track （string）：曲目名称
start_time （数字）：开始时间（含）
end_time （数字）：结束时间（不包括节拍）

例子：

{
  "track": "piano",
  "start_time": 0,
  "end_time": 4
}

`get_notes`

查询备注，可选择按曲目和/或时间范围进行筛选。

参数：

track （字符串，可选）：按曲目名称筛选
start_time （数字，可选）：按开始时间（含）筛选
end_time （数字，可选）：按结束时间筛选（不包括）

______________________________________________________________________

Harmony工具

`add_chords`

为乐曲添加和弦级数。验证和弦符号并返回每个和弦的和弦音调。

参数：

chords （数组）：和弦对象列表，包括：

- beat （数字）：和弦开始的节拍位置 - chord （字符串）：和弦符号（例如，“C”、“Cm7”、“G7”、“Fmaj9”） - duration （数字）：和弦的节拍持续时间

退货：

success （boolean）：是否已成功添加所有和弦
chords_added （array）：添加的和弦及其chord_tones的列表
errors （数组）：无效和弦符号的任何验证错误

支持的和弦符号： 服务器使用 pychord 和弦解析库。常见的和弦类型包括：

专业： C, D, F#
未成年人： Cm, Dm, Bbm
优势7： C7, G7, D7
大七： Cmaj7, Fmaj7
小七： Cm7, Dm7
减少： Cdim, Bdim
增强型： Caug
暂停的： Csus4, Dsus2
扩展： C9, C11, C13, Cadd9
第六和弦： C6, Cm6

例子：

{
  "chords": [
    {"beat": 0, "chord": "C", "duration": 4},
    {"beat": 4, "chord": "F", "duration": 4},
    {"beat": 8, "chord": "G7", "duration": 4},
    {"beat": 12, "chord": "C", "duration": 4}
  ]
}

重叠行为： 当后面的和弦与现有和弦重叠时，原始和弦会被拆分并部分删除，为新和弦腾出空间。

`get_chords_in_range`

让所有和弦都在一个节拍范围内。

参数：

start_beat （数字）：节拍范围的开始
end_beat （数字）：节拍范围结束

退货： 指定范围内的和弦对象数组。

例子：

{
  "start_beat": 0,
  "end_beat": 8
}

`remove_chords_in_range`

移除节拍范围内的和弦。同时清除所有标记的音符，因为和声上下文变得陈旧。

参数：

start_beat （数字）：节拍范围的开始
end_beat （数字）：节拍范围结束

______________________________________________________________________

验证工具

`flag_notes`

超出计划和弦级数的Flag音符。可用于检测旋律和声冲突。

参数：

tracks （字符串数组）：要检查的曲目名称列表
start_beat （数字）：节拍范围的开始
end_beat （数字）：节拍范围结束

退货：

flagged_count （number）：标记的笔记数量
message （string）：状态消息

行为：

自动首先清除所有先前的标志
对于指定轨迹和范围内的每个音符：

- 在音符的起始节拍处查找活动和弦 - 检查音符的音高等级是否与和弦音调匹配 - 如果笔记不匹配，则标记该笔记（设置 flagged: true)

间隙中的音符（不存在和弦）不会被标记（缺少和声不是错误）

例子：

{
  "tracks": ["melody", "piano"],
  "start_beat": 0,
  "end_beat": 16
}

`remove_flagged_notes`

从文章中删除所有标记的笔记。

退货：

removed_notes （array）：已删除的音符列表，包括曲目、音高、开始、持续时间
count （number）：已删除的钞票数量

自我纠正工作流程示例：

添加旋律和和弦进程
Flag注意到不符合和谐： flag_notes(["melody"], 0, 16)
查看标记的笔记： get_notes("melody", 0, 16) （寻找 flagged: true)
删除有问题的笔记： remove_flagged_notes()
添加更正的注释： add_notes([...])
验证： flag_notes(["melody"], 0, 16) （应返回0）

______________________________________________________________________

效用

`undo`

撤消上一个操作。最多支持10个撤消步骤。

`redo`

重做上次未执行的操作。

`export_midi`

将当前曲目导出为MIDI文件。

参数：

filepath （string）：保存MIDI文件的路径（将添加 .mid 如果缺失）

例子：

{
  "filepath": "my_composition.mid"
}

MIDI导出功能：

表达式求值（转换 "9 + 1/3" 精确到刻度）
多音轨支持（每种乐器一个MIDI音轨）
自动通道分配（通道9上的鼓）
各部分的节奏和时间签名
通用MIDI乐器映射
每拍480滴答（标准分辨率）
固定速度：64（中等）

______________________________________________________________________

通用MIDI乐器映射

该服务器支持128种通用MIDI乐器。常见示例：

钢琴（0-7）：

piano, acoustic_grand_piano → 0
bright_acoustic_piano → 1
electric_piano_1 → 4
harpsichord → 6

字符串（40-47）：

violin → 40
viola → 41
cello → 42
harp → 46

黄铜（56-63）：

trumpet → 56
trombone → 57
french_horn → 60

木风：

flute → 73
clarinet → 71
saxophone → 64

低音（32-39）：

bass, acoustic_bass → 32
electric_bass_finger → 33
synth_bass_1 → 38

吉他（24-31）：

guitar, acoustic_guitar_nylon → 24
electric_guitar_clean → 27
distortion_guitar → 30

打击：

drums, percussion → 通道9（GM打击乐）

有关完整列表，请参阅 src/midi_gen_mcp/midi_export.py.

注：未知乐器默认为钢琴（0）。

______________________________________________________________________

状态模式

服务器保持具有以下结构的内存状态：

{
  "title": str,                    # Piece title (default: "Untitled")
  "tracks": {                      # Track dictionary
    "track_name": {
      "name": str,
      "instrument": str
    }
  },
  "notes": [                       # Flat list of notes
    {
      "track": str,
      "pitch": int,                # 0-127 (60 = Middle C)
      "start": str | float,        # Beats, supports expressions
      "duration": str | float,     # Beats, supports expressions
      "flagged": bool              # Optional, set by flag_notes tool
    }
  ],
  "sections": [                    # Section list (sorted by start_measure)
    {
      "name": str,
      "start_measure": int,
      "end_measure": int,
      "tempo": int,
      "time_signature": str,
      "key": str,
      "description": str
    }
  ],
  "chord_progression": [           # Chord progression (sorted by beat)
    {
      "beat": float,
      "chord": str,
      "duration": float,
      "chord_tones": list[str]     # Pitch classes (e.g., ["C", "E", "G"])
    }
  ],
  "undo_stack": list,              # Max 10 state snapshots
  "redo_stack": list               # Cleared on new actions
}

______________________________________________________________________

发展

运行测试

# Run all tests
uv run pytest

# Run with verbose output
uv run pytest -v

# Run specific test file
uv run pytest tests/test_note.py

# Using Make (uses uv internally)
make test

测试覆盖范围：

8个测试模块中的116个测试
状态管理（8项测试）
歌曲工具（4次测试）
结构工具（13项测试）
轨道工具（9次测试）
注释操作（17次测试）
MIDI导出（20次测试）
和弦分析器（16次测试）
Harmony工具（18项测试）
验证工具（13项测试）

项目结构

midi-gen-mcp/
├── src/
│   └── midi_gen_mcp/
│       ├── __init__.py
│       ├── server.py           # MCP server entry point
│       ├── state.py            # In-memory state management
│       ├── midi_export.py      # MIDI file generation
│       ├── chord_parser.py     # Chord symbol parsing (pychord wrapper)
│       └── tools/              # Tool implementations
│           ├── __init__.py
│           ├── song.py         # set_title, get_piece_info
│           ├── structure.py    # add_section, edit_section, get_sections
│           ├── track.py        # add_track, remove_track, get_tracks
│           ├── note.py         # add_notes, remove_notes_in_range, get_notes
│           ├── harmony.py      # add_chords, get_chords_in_range, remove_chords_in_range
│           ├── validation.py   # flag_notes, remove_flagged_notes
│           └── utility.py      # undo, redo, export_midi
├── tests/
│   ├── test_state.py
│   ├── test_song.py
│   ├── test_structure.py
│   ├── test_track.py
│   ├── test_note.py
│   ├── test_midi_export.py
│   ├── test_chord_parser.py
│   ├── test_harmony_tools.py
│   └── test_validation_tools.py
├── pyproject.toml
├── Makefile
├── README.md
├── PLANNING.md
└── DESIGN_DOC.md

______________________________________________________________________

设计理念

关键原则： MCP工具仅是确定性操作。所有的音乐理论，作曲决策和创造性推理都发生在法学硕士（克劳德）。

MCP服务器的功能：

✅ 笔记、曲目、章节的CRUD操作
✅ MIDI文件导出
✅ 状态管理（撤消/重做）
✅ 数据验证

MCP服务器不做什么：

❌ 生成旋律或和声
❌ 做出组合决策
❌ 应用音乐理论规则
❌ 动态表达式（速度固定为64）

LLM使用这些低级工具通过按顺序调用它们来创作音乐。

______________________________________________________________________

工作流示例

以下是克劳德如何创作一首简单的旋律：

创建结构：

   add_section("intro", 1, 4, 120, "4/4", "C")

添加曲目：

   add_track("piano", "piano")
   add_track("bass", "acoustic_bass")

谱写旋律：

   add_notes([
     {"track": "piano", "pitch": 60, "start": 0, "duration": 1},
     {"track": "piano", "pitch": 64, "start": 1, "duration": 1},
     {"track": "piano", "pitch": 67, "start": 2, "duration": 1},
     {"track": "piano", "pitch": 72, "start": 3, "duration": 1}
   ])

添加低音线：

   add_notes([
     {"track": "bass", "pitch": 48, "start": 0, "duration": 4}
   ])

出口：

   export_midi("my_composition.mid")

______________________________________________________________________

局限性

无动态表达式： 所有音符使用固定速度（64）
无发音： 无断奏、连奏或其他演奏标记
无俯仰弯曲或调制： 不支持MIDI CC消息
无音频渲染： 仅导出MIDI（使用外部DAW播放）
仅在内存中： 状态在会话之间不持久
每节单节奏： 分段内没有渐进的节奏变化

______________________________________________________________________

未来的增强功能

未来可能增加的内容（不在当前范围内）：

\[\]每张钞票的速度动态
\[\]MIDI CC消息（调制、维持、表达）
\[\]变桨弯曲支撑
\[\]将会话保存/加载为JSON
\[\]实时MIDI输出
\[\]音频渲染（基于声音字体）

______________________________________________________________________

许可证

有关许可证信息，请参阅存储库。

______________________________________________________________________

贡献

这是 核心组件#1：MCP服务器 从整体项目来看。有关完整系统的信息（包括音乐理论技能和前端），请参阅 DESIGN_DOC.md.

______________________________________________________________________

状态： 核心MCP服务器已完成116项测试。所有功能，包括和谐和验证工具都已实现。已准备好与Claude Desktop集成。

Midi Gen MCP

快速接入

详细介绍

MIDI生成MCP

特性

安装

先决条件

来源

快速设置

用法

运行MCP服务器

为Claude桌面配置

MCP工具参考

歌曲管理

set_title

get_piece_info

结构管理

add_section

edit_section

get_sections

跟踪管理

add_track

remove_track

get_tracks

注释操作

add_notes

remove_notes_in_range

get_notes

Harmony工具

add_chords

get_chords_in_range

remove_chords_in_range

验证工具

flag_notes

remove_flagged_notes

效用

undo

redo

export_midi

通用MIDI乐器映射

状态模式

发展

运行测试

项目结构

设计理念

工作流示例

局限性

未来的增强功能

许可证

相关文档

贡献

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

`set_title`

`get_piece_info`

`add_section`

`edit_section`

`get_sections`

`add_track`

`remove_track`

`get_tracks`

`add_notes`

`remove_notes_in_range`

`get_notes`

`add_chords`

`get_chords_in_range`

`remove_chords_in_range`

`flag_notes`

`remove_flagged_notes`

`undo`

`redo`

`export_midi`