Midi Gen MCP

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）：已删除的钞票数量

自我纠正工作流程示例：

1. 添加旋律和和弦进程
2. Flag注意到不符合和谐： flag_notes(["melody"], 0, 16)
3. 查看标记的笔记： get_notes("melody", 0, 16) （寻找 flagged: true)
4. 删除有问题的笔记： remove_flagged_notes()
5. 添加更正的注释： add_notes([...])
6. 验证： 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使用这些低级工具通过按顺序调用它们来创作音乐。

______________________________________________________________________

工作流示例

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

1. 创建结构：

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

1. 添加曲目：

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

1. 谱写旋律：

   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}
   ])

1. 添加低音线：

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

1. 出口：

   export_midi("my_composition.mid")

______________________________________________________________________

局限性

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

______________________________________________________________________

未来的增强功能

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

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

______________________________________________________________________

许可证

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

______________________________________________________________________

相关文档

• 规划.md -实施规划和进展
• 设计_DOC.md -总体系统设计
• MCP文件 -模型上下文协议

______________________________________________________________________

贡献

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

______________________________________________________________________

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