MIDI MCP Server

MIDI MCP Server

A Model Context Protocol (MCP) server for AI-driven MIDI composition. Generate MIDI files from structured JSON data, with chord name support, an interactive piano-roll preview UI, and multiple deployment modes.

Looking for the Agent Skills approach? It composes better songs with less context: tubone24/midi-agent-skill

---

Features

• Two MCP tools: create_midi (with interactive preview UI) and parse_chord
• Rich pitch input: MIDI numbers, note name strings ("C4"), pitch arrays, or chord names ("Cmaj7")
• Chord library: 25+ chord qualities — major, minor, dim, aug, 7th, maj7, m7, sus2, sus4, power, and more
• Flexible durations: numeric beats, standard strings ('4', '8'), dotted ('d4'), triplet ('T8')
• Music theory resources: 7 built-in reference documents accessible as MCP resources
• Three transport modes: stdio, HTTP, or Cloudflare Workers (remote)
• MCP App UI: Piano-roll visualization and audio playback rendered directly in the conversation

---

Deployment Options

Option A — Remote (Cloudflare Workers)

A pre-deployed remote server is available:

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

Add it to any MCP client that supports Streamable HTTP (e.g., Claude.ai):

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

Option B — Local stdio (recommended for desktop clients)

Build and configure as a local stdio server:

npm install
npm run build

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

Option C — Local HTTP

Run as a local Streamable HTTP server:

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

The server exposes:

• POST /mcp — MCP Streamable HTTP endpoint
• GET /health — Health check ({"status":"ok","version":"0.2.0"})

---

Tools

create_midi

Generate a MIDI file from structured composition data. Returns base64-encoded MIDI and renders an interactive piano-roll preview with audio playback in supported MCP clients (MCP App).

Input

Field	Type	Required	Description
title	string	✓	Title of the composition
composition	object	✓	Composition data (see schema below)

Output (structured content)

Field	Type	Description
midiBase64	string	Base64-encoded MIDI file data
title	string	Composition title
bpm	number	Tempo used
trackCount	number	Number of tracks generated

---

parse_chord

Parse a chord name and return its component MIDI pitches and note names. Useful for understanding voicings before composing.

Input

Field	Type	Required	Description
chord	string	✓	Chord name, e.g. "Cmaj7", "F#m7", "G7sus4"
octave	number	—	Root octave (default: 4)

Output example

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

---

Composition Schema

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

Pitch Input Formats

Format	Example	Description
MIDI number	60	Standard MIDI note number (0–127)
Note name	"C4"	Letter + optional accidental + octave
Pitch array	[60, 64, 67]	Multiple pitches played simultaneously
Chord field	chord: "Cmaj7"	Chord name expanded automatically

Supported accidentals: # (sharp), b (flat). Examples: "F#5", "Bb3".

Duration Reference

Value	Description
'1'	Whole note
'2'	Half note
'4'	Quarter note
'8'	Eighth note
'16'	Sixteenth note
'32'	Thirty-second note
'd1' 'd2' 'd4' 'd8' 'd16'	Dotted variants
'dd4'	Double-dotted quarter
'T4' 'T8' …	Triplet variants
4 (number)	Beat-based: 1=quarter, 2=half, 4=whole, 0.5=eighth

Supported Chord Qualities

Quality	Example	Description
(none) / maj	C, Cmaj	Major
m / min	Dm	Minor
dim	Bdim	Diminished
aug	Eaug	Augmented
7	G7	Dominant 7th
maj7 / M7	Cmaj7	Major 7th
m7 / min7	Am7	Minor 7th
dim7	Bdim7	Diminished 7th
m7b5	Bm7b5	Half-diminished
aug7	Eaug7	Augmented 7th
6 / m6	C6, Am6	6th
9 / maj9 / m9	G9	9th variants
add9	Cadd9	Add 9th
11 / 13	C11	Extended
sus2 / sus4	Gsus4	Suspended
7sus4 / 7sus2	G7sus4	7th suspended
power / 5	G5	Power chord

---

MCP Resources

The server exposes 7 music theory reference documents as MCP resources:

URI	Description
music-theory://harmony	Intervals, chord types, diatonic chords, cadences, voice leading
music-theory://chord-progressions	Common progressions by mood/genre, substitutions, modulation
music-theory://counterpoint	Species counterpoint rules, consonance/dissonance, motion types
music-theory://modes-scales	Diatonic modes, minor scale variants, pentatonic/blues, genre guide
music-theory://orchestration	Instrument ranges, GM program numbers, texture types
music-theory://rhythm-patterns	Time signatures, MIDI duration reference, genre grooves
music-theory://voice-leading	Forbidden parallels, voicing strategies, non-chord tones

MCP clients that support resource reading can pass these to the AI as context, enabling theory-aware composition.

---

Example Composition

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

---

Demo

The prompt below generates an 8-bar melodic minor choral piece:

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

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

melodic_minor_chorus.mid

---

Build & Development

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

---

Dependencies

Package	Purpose
@modelcontextprotocol/sdk	MCP server implementation (stdio & HTTP transports)
@modelcontextprotocol/ext-apps	MCP Apps extension — interactive UI in conversation
midi-writer-js	MIDI file generation
@tonejs/midi	MIDI parsing (preview UI)
soundfont-player	Audio playback in preview UI
zod	Input schema validation