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

Output (structured content)

---

parse_chord

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

Input

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

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

Duration Reference

Supported Chord Qualities

---

MCP Resources

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

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