GarageBand Practice MCP

Local TypeScript MCP server for creating authorized song-practice projects for GarageBand.

Creates local GarageBand practice workspaces from authorised MIDI, including native-score handoff files and one-bar loop practice assets. No cloud service or paid tooling is required.

Daily Workflow

The intended Codex workflow is:

1. Run diagnose_setup to confirm GarageBand, MIDI keyboard hints, audio interface hints, Audio MIDI Setup, and optional MuseScore rendering support.
2. Run create_practice_project for the song, or reuse an existing project slug.
3. Import authorized MIDI with import_user_midi, or use search_public_domain_midi and import_public_domain_midi for Mutopia Project material.
4. Run generate_bar_practice_assets to produce a named, one-bar MIDI file for each measure.
5. Run open_in_garageband to open the saved native GarageBand project, or import the active MIDI on the first session.
6. In GarageBand, use the native Score Editor for notation, Cycle for a selected bar, and the empty piano track for live keyboard input.
7. Save the session as garageband/<song-slug>.band.

Example Codex request:

Use garageband-practice to open bach-prelude-c-major-bwv-846 in GarageBand, then save a session snapshot and push it.

Expected device names can be configured before starting Codex:

export GARAGEBAND_EXPECTED_MIDI_DEVICES="KeyLab,Arturia"
export GARAGEBAND_EXPECTED_AUDIO_INTERFACES="Scarlett,Focusrite"

Content Policy

• Accept user-supplied MIDI/MusicXML files when the user is authorized to use them.
• Search public-domain/open-license catalogues only.
• Mutopia Project is the first supported catalogue because it publishes PDF, MIDI, and LilyPond downloads under public-domain or Creative Commons terms.
• Do not search for or download copyrighted MIDI from unauthorized sources.
• Later AI approximation work must start from user-provided chords/structure and be labeled as an arrangement, not a transcription.

Project Layout

songs/<slug>/
  source/
  midi/
  charts/
  garageband/README.md
  project.json

Project metadata stores artifact paths relative to each song folder, for example midi/song.mid or charts/song.musicxml. Runtime tools resolve those paths locally when opening GarageBand or rendering practice files.

Tracked session artifacts:

• songs/**/project.json
• songs/**/source/*.mid and songs/**/source/*.midi
• songs/**/midi/*.mid and songs/**/midi/*.midi
• songs/**/charts/*.musicxml
• selected songs/**/charts/*.pdf score files
• songs/**/practice/index.html
• songs/**/garageband/README.md

Ignored session outputs:

• GarageBand .band project packages
• audio bounces such as .wav, .aif, .m4a, and .mp3
• dependency, build, cache, and log files

Tools

• create_practice_project
• import_user_midi
• search_public_domain_midi
• import_public_domain_midi
• generate_piano_grand_staff_chart
• generate_bar_practice_assets
• open_in_garageband
• save_session_snapshot
• diagnose_setup

Local Development

npm install
npm run check
npm test
npm run audit:prod
npm run mcp

GarageBand Flow

1. Create a practice project.
2. Import a user-supplied MIDI file, or search Mutopia and import a selected Mutopia MIDI result.
3. Generate the piano grand-staff chart.
4. Generate bar practice assets for targeted looping.
5. Open the active MIDI in GarageBand on the first session, then use GarageBand's native Score Editor for notation.
6. Save the .band project in the song's garageband/ folder. Future opens prefer this native session automatically.
7. Run save_session_snapshot to summarize trackable song artifacts, then optionally commit and push them.

MusicXML is the durable notation interchange format. GarageBand project files are intentionally treated as a manual handoff target because .band automation is not stable enough for V1.