music21-mcp

MCP server exposing 16 music21 MIDI analysis and editing tools to AI agents. Built spec-driven with TDD — 120 tests, all green.

What it does

Give an AI agent a MIDI file and it can:

• Read — parse MIDI, detect key, analyze chord progressions
• Edit — transpose, change velocity, filter notes, replace chords, merge files, quantize timings
• Generate — reharmonize progressions, harmonize melodies
• Analyze — detect modulations, extract melody, identify song form, search for patterns

Tools

Phase	Tool	What it does
1a	parse_midi_file	Load a .mid file into a music21 stream
1a	analyze_key	Detect key, mode, and confidence
1a	export_midi	Write a stream to a .mid file
1c	transpose_midi	Transpose by semitones or to a target key
1c	change_velocity	Scale, set, or offset note velocities (clamped 1–127)
1c	modify_notes	Remove/select notes by pitch range, shift octaves
1c	replace_chord_at	Replace a chord at a specific bar/beat
1c	merge_midi	Overlay two streams (flat or multi-part score)
1c	quantize_midi	Snap note timings to quarter/eighth/sixteenth grid
2	reharmonize	Replace chords with diatonic or jazz substitutions
2	harmonize_melody	Generate block chord accompaniment from a melody
3	analyze_chord_progression	Identify chords + Roman numerals in a progression
3	extract_melody	Isolate the melody line (highest pitch per offset)
3	detect_modulations	Find key changes via sliding window analysis
3	analyze_form	Identify song sections (A, B, A') by register changes
3	search_pattern	Find melodic patterns by exact pitch or interval sequence

Getting started

Prerequisites

• Python 3.11+
• A virtual environment (recommended)

Install

cd music21-mcp

# Create and activate venv
python3 -m venv venv
source venv/bin/activate

# Install the package in editable mode
pip install -e .

# Install MCP server dependency
pip install mcp

Run tests

# All 120 tests
pytest -v

# Just one tool's tests
pytest tests/test_transpose_midi.py -v

Use as MCP server

The server runs over stdio, compatible with any MCP-aware client (Claude Desktop, Cursor, etc).

# Start the server
python -m music21_mcp.server

To configure in an MCP client, add to your client's MCP config:

{
  "mcpServers": {
    "music21-mcp": {
      "command": "python",
      "args": ["-m", "music21_mcp.server"],
      "cwd": "/path/to/music21-mcp"
    }
  }
}

Or if using the project venv:

{
  "mcpServers": {
    "music21-mcp": {
      "command": "/path/to/music21-mcp/venv/bin/python",
      "args": ["-m", "music21_mcp.server"]
    }
  }
}

Use directly in Python

Every tool is a pure function you can call without the MCP layer:

from music21_mcp.tools.parse_midi import parse_midi_file
from music21_mcp.tools.analyze_key import analyze_key
from music21_mcp.tools.transpose_midi import transpose_midi
from music21_mcp.tools.export_midi import export_midi

# Load a MIDI file
stream = parse_midi_file("song.mid")

# Detect the key
key_info = analyze_key(stream)
print(key_info)
# {'key': 'C major', 'mode': 'major', 'confidence': 0.797}

# Transpose to F major
transposed = transpose_midi(stream, target_key="F")

# Save the result
export_midi(transposed, "song_in_f.mid")

Example: the full pipeline

from music21_mcp.tools import (
    parse_midi_file, analyze_key, transpose_midi,
    change_velocity, quantize_midi, export_midi,
)

# Load
s = parse_midi_file("input.mid")

# Detect key
print(analyze_key(s))

# Transpose up 2 semitones, make 20% louder, quantize to 16th notes
s = transpose_midi(s, semitones=2)
s = change_velocity(s, scale=1.2)
s = quantize_midi(s, grid="sixteenth")

# Save
export_midi(s, "output.mid")

Example prompts for testing

Single-tool prompts to verify each tool works in isolation:

1. Parse only — "Load song.mid with parse_midi_file and tell me how many parts and measures it has."

2. Key detection — "Use parse_midi_file to load song.mid, then analyze_key to tell me the key, mode, and confidence."

3. Export — "Load song.mid with parse_midi_file and export it to copy.mid with export_midi. Did the file size match?"

4. Transpose — "Parse song.mid and transpose it down 3 semitones. Export to song_down.mid."

5. Transpose to key — "Load song.mid, detect its key, then transpose it to E minor. Export to song_em.mid."

6. Velocity — "Parse song.mid, set all velocities to a fixed value of 90. Export to song_vel90.mid."

7. Velocity boost — "Load song.mid and scale all velocities by 1.3 (clamped to 127). Export to song_louder.mid."

8. Filter notes — "Parse song.mid and remove all notes below C3. Export to song_no_bass.mid."

9. Octave shift — "Load song.mid and shift everything up 1 octave. Export to song_oct_up.mid."

10. Replace chord — "Parse song.mid and replace the chord at bar 2, beat 1 with a C major triad. Export to song_newchord.mid."

11. Merge — "Load drums.mid and bass.mid, merge them into a single file. Export to drum_and_bass.mid."

12. Quantize — "Parse song.mid and quantize all timings to a sixteenth-note grid. Export to song_quantized.mid."

13. Reharmonize — "Load song.mid and reharmonize the chord progression using jazz substitutions. Export to song_jazz.mid."

14. Harmonize — "Parse melody.mid and generate block chord accompaniment from the melody line. Export to melody_with_chords.mid."

15. Chord analysis — "Load song.mid and analyze the chord progression. Give me the chords and Roman numerals."

16. Extract melody — "Parse song.mid and extract just the melody line. Export to melody_only.mid."

17. Detect modulations — "Load song.mid and find all key changes. Tell me where each modulation happens."

18. Analyze form — "Parse song.mid and identify the song structure (A, B, A' sections)."

19. Search pattern — "Load song.mid and search for the pitch sequence C4-E4-G4. Tell me where it occurs."

Multi-tool chains to test tool composition:

20. Full analysis — "Load song.mid. Detect the key, analyze the chord progression, extract the melody, and analyze the song form. Give me a complete analysis report."

21. Transpose and harmonize — "Parse song.mid, transpose up 5 semitones, then reharmonize the result with jazz substitutions. Export to song_jazz_up.mid."

22. Clean and quantize — "Load song.mid, remove all notes below C2, quantize to an eighth-note grid, and scale velocities by 0.8. Export to song_cleaned.mid."

23. Melody extraction pipeline — "Parse song.mid, extract the melody, harmonize it with block chords, and export to melody_harmonized.mid."

24. Key-aware reharm — "Load song.mid, detect the key, then reharmonize using diatonic substitutions appropriate for that key. Export to song_diatonic.mid."

25. Modulation-aware transpose — "Parse song.mid, detect all modulations, then transpose the whole piece so the first key becomes A minor. Export to song_am.mid."

26. Pattern search then replace — "Load song.mid, search for the interval sequence [2, 2] (two whole steps up), and replace each match with a diminished triad. Export to song_dim.mid."

27. Form-aware analysis — "Parse song.mid, analyze the form to find the B section, then extract just the melody from that section and harmonize it. Export to b_section_harmonized.mid."

28. Multi-file merge and clean — "Load drums.mid, bass.mid, and keys.mid. Merge all three, quantize to a sixteenth grid, and scale velocities to 100. Export to full_band.mid."

29. End-to-end remix — "Load song.mid. Detect key, transpose down 2 semitones, quantize to eighth notes, reharmonize with jazz substitutions, boost velocity by 1.4, and export to song_remix.mid."

Architecture

src/music21_mcp/
  __init__.py          # Package entry
  server.py            # FastMCP server — 16 tool wrappers returning JSON
  tools/
    parse_midi.py      # Phase 1a
    analyze_key.py
    export_midi.py
    transpose_midi.py  # Phase 1c
    change_velocity.py
    modify_notes.py
    replace_chord_at.py
    merge_midi.py
    quantize_midi.py
    reharmonize.py     # Phase 2
    harmonize_melody.py
    analyze_chord_progression.py  # Phase 3
    extract_melody.py
    detect_modulations.py
    analyze_form.py
    search_pattern.py

tests/
    test_*.py          # One test file per tool, plus server + e2e tests

Each tool is a pure function that takes a music21 Stream and returns a Stream or dict. The MCP server layer handles file-path-to-stream conversion and JSON serialization. This separation means tools are testable without the MCP protocol and usable as a plain Python library.

Tech

• music21 — MIT's music theory and analysis toolkit
• MCP — Model Context Protocol for AI agent tool calling
• Python 3.11+, pytest, strict TDD

License

MIT