MIDI MCP Server

MIDI MCP 服务

一个用于 AI 驱动的 MIDI 创作的 Model Context Protocol (MCP) 服务。通过结构化 JSON 数据生成 MIDI 文件，支持和弦名称、交互式钢琴卷帘预览界面和多种部署模式。

想了解 Agent Skills 方案？ 它能用更少的上下文创作出更好的歌曲： tubone24/midi-agent-skill

---

功能

• 两种 MCP 工具：create_midi（带交互式预览界面）和 parse_chord
• 丰富的音高输入：MIDI 数字、音符名称字符串（"C4"）、音高数组或和弦名称（"Cmaj7"）
• 和弦库：25 种以上的和弦类型——大调、小调、减和弦、增和弦、七和弦、大七和弦、小七和弦、挂二和弦、挂四和弦、强力和弦等
• 灵活的时值：数字节拍、标准字符串（'4'、'8'）、附点（'d4'）、三连音（'T8'）
• 乐理资源：7 篇内置参考文档，可作为 MCP 资源访问
• 三种传输模式：stdio、HTTP 或 Cloudflare Workers（远程）
• MCP App 界面：在对话中直接呈现钢琴卷帘可视化和音频播放

---

部署选项

选项 A — 远程（Cloudflare Workers）

现已提供预部署的远程服务：

https://midi-mcp-server.tubone24.workers.dev/mcp

将其添加到任何支持 Streamable HTTP 的 MCP 客户端（例如 Claude.ai）：

{
  "mcpServers": {
    "midi": {
      "type": "http",
      "url": "https://midi-mcp-server.tubone24.workers.dev/mcp"
    }
  }
}

选项 B — 本地 stdio（推荐用于桌面客户端）

构建并配置为本地 stdio 服务：

npm install
npm run build

{
  "mcpServers": {
    "musicComposer": {
      "command": "node",
      "args": ["/path/to/midi-mcp-server/build/index.js"]
    }
  }
}

选项 C — 本地 HTTP

作为本地 Streamable HTTP 服务运行：

node build/index.js --http
# or with a custom port:
node build/index.js --http --port=8080

服务提供：

• POST /mcp — MCP Streamable HTTP 端点
• GET /health — 健康检查（{"status":"ok","version":"0.2.0"}）

---

工具

create_midi

根据结构化创作数据生成 MIDI 文件。返回 Base64 编码的 MIDI，并在支持的 MCP 客户端（MCP App）中呈现交互式钢琴卷帘预览和音频播放。

输入

字段	类型	必填	描述
title	string	✓	创作标题
composition	object	✓	创作数据（参见下方架构）

输出（结构化内容）

字段	类型	描述
midiBase64	string	Base64 编码的 MIDI 文件数据
title	string	创作标题
bpm	number	使用的速度
trackCount	number	生成的音轨数量

---

parse_chord

解析和弦名称并返回其组成的 MIDI 音高和音符名称。可用于在创作前了解和弦转位。

输入

字段	类型	必填	描述
chord	string	✓	和弦名称，例如 "Cmaj7"、"F#m7"、"G7sus4"
octave	number	—	根音八度（默认值：4）

输出示例

{
  "chord": "Cmaj7",
  "octave": 4,
  "midiNumbers": [60, 64, 67, 71],
  "noteNames": ["C4", "E4", "G4", "B4"]
}

---

创作架构

{
  "bpm": 120,                              // tempo (also accepted: "tempo")
  "timeSignature": { "numerator": 4, "denominator": 4 },  // optional, default 4/4
  "tracks": [
    {
      "name": "Piano",                     // optional
      "instrument": 0,                     // GM program number 0–127 (optional)
      "notes": [
        {
          "pitch": 60,                     // MIDI number, note name "C4", or array [60, 64, 67]
          "chord": "Cmaj7",                // OR use chord name (overrides pitch)
          "beat": 1,                       // beat position (1-based); OR use startTime
          "startTime": 0,                  // tick offset (alias: "time")
          "duration": "4",                 // see Duration Reference below
          "velocity": 100,                 // 0–127 (optional, default 100)
          "channel": 0                     // MIDI channel 0–15 (optional)
        }
      ]
    }
  ]
}

音高输入格式

格式	示例	描述
MIDI 数字	60	标准 MIDI 音符编号（0–127）
音符名称	"C4"	字母 + 可选变音记号 + 八度
音高数组	[60, 64, 67]	同时演奏的多个音高
和弦字段	chord: "Cmaj7"	自动展开和弦名称

支持的变音记号：#（升号）、b（降号）。示例："F#5"、"Bb3"。

时值参考

值	描述
'1'	全音符
'2'	二分音符
'4'	四分音符
'8'	八分音符
'16'	十六分音符
'32'	三十二分音符
'd1' 'd2' 'd4' 'd8' 'd16'	附点变体
'dd4'	复附点四分音符
'T4' 'T8' …	三连音变体
4（数字）	基于拍数：1=四分音符，2=二分音符，4=全音符，0.5=八分音符

支持的和弦性质

性质	示例	描述
(无) / maj	C，Cmaj	大调
m / min	Dm	小调
dim	Bdim	减和弦
aug	Eaug	增和弦
7	G7	属七和弦
maj7 / M7	Cmaj7	大七和弦
m7 / min7	Am7	小七和弦
dim7	Bdim7	减七和弦
m7b5	Bm7b5	半减和弦
aug7	Eaug7	增七和弦
6 / m6	C6，Am6	六和弦
9 / maj9 / m9	G9	九和弦变体
add9	Cadd9	加九和弦
11 / 13	C11	延伸和弦
sus2 / sus4	Gsus4	挂留和弦
7sus4 / 7sus2	G7sus4	七和弦挂留和弦
power / 5	G5	强力和弦

---

MCP 资源

该服务以 MCP 资源的形式提供 7 份音乐理论参考文档：

URI	描述
music-theory://harmony	音程、和弦类型、自然调和弦、终止式、声部进行
music-theory://chord-progressions	按情绪／流派分类的常见和弦进行、替代和弦、转调
music-theory://counterpoint	对位法各类规则、协和／不协和、进行类型
music-theory://modes-scales	自然调式、小调音阶变体、五声音阶／布鲁斯音阶、流派指南
music-theory://orchestration	乐器音域、GM 音色编号、织体类型
music-theory://rhythm-patterns	拍号、MIDI 时值参考、流派律动
music-theory://voice-leading	禁止平行进行、声部配置策略、非和弦音

支持读取资源的 MCP 客户端可以将这些内容作为上下文传递给 AI，从而实现兼顾乐理的创作。

---

创作示例

const composition = {
  bpm: 120,
  timeSignature: { numerator: 4, denominator: 4 },
  tracks: [
    {
      name: "Piano",
      instrument: 0,
      notes: [
        { chord: "Cmaj7", beat: 1, duration: "2", velocity: 90 },
        { chord: "Am7",   beat: 3, duration: "2", velocity: 90 },
        { chord: "Fmaj7", beat: 5, duration: "2", velocity: 90 },
        { chord: "G7",    beat: 7, duration: "2", velocity: 90 }
      ]
    },
    {
      name: "Melody",
      instrument: 0,
      notes: [
        { pitch: "E4", beat: 1, duration: "4", velocity: 100 },
        { pitch: "G4", beat: 2, duration: "4", velocity: 100 },
        { pitch: "A4", beat: 3, duration: "2", velocity: 110 }
      ]
    }
  ]
};

---

演示

以下提示词会生成一段 8 小节的旋律小调合唱曲：

Create an 8-bar choral piece in a slightly minor, melodic scale.

https://github.com/user-attachments/assets/e20ebef0-fdbf-4e72-910d-41b94183f9d9

旋律小调合唱曲.mid

---

构建与开发

npm install

# Full build (UI + server)
npm run build

# Build steps individually
npm run build:ui     # Vite — builds the MCP App preview HTML
npm run build:server # tsc — compiles TypeScript server

# Deploy to Cloudflare Workers
npm run deploy

# Run tests
npm test
npm run test:coverage

---

依赖项

软件包	用途
@modelcontextprotocol/sdk	MCP 服务实现（stdio 和 HTTP 传输）
@modelcontextprotocol/ext-apps	MCP Apps 扩展——在对话中提供交互式 UI
midi-writer-js	MIDI 文件生成
@tonejs/midi	MIDI 解析（预览 UI）
soundfont-player	预览 UI 中的音频播放
zod	输入模式验证