music.build

An MCP server that lets AI agents compose music. Built on a typed, immutable music theory library — notes, voices, harmony, form, and transforms are first-class values that agents build up incrementally and export to MIDI and LilyPond notation.

Apache 2.0 · Java 25 · JPMS · Maven

What it does

Connect music.build to Claude Desktop or any MCP-capable agent. The agent can:

• Build note sequences with full pitch spelling, rhythm, and articulation
• Layer voices into a score, assign instruments, set key and tempo
• Generate walking bass lines, chord voicings, and diatonic harmonizations
• Assemble multi-section forms with volta endings
• Check voice leading and range rules
• Export to MIDI, LilyPond PDF, and a replayable session log

No piano roll. No GUI. The composition emerges from tool calls.

Setup

Prerequisites

• Java 25 (java -version should report 25.x)
• LilyPond 2.24+ (optional — required only for PDF export; MIDI works without it)

Clone and run

git clone https://github.com/deer/music.build
cd music.build
./mvnw exec:java -pl music-server

All dependencies (base.build, codemodel.build, serve.build) are on Maven Central — no local installs required.

The MCP server listens on http://localhost:3000/mcp. To use a different port:

PORT=4000 ./mvnw exec:java -pl music-server

Connect to Claude Code

If you're using Claude Code, install the compose plugin from this repo's marketplace. It registers the MCP server and loads the composition skill automatically. Start the server, then open Claude Code in this directory — the music-server tools and skill are available in every session.

Connect to Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows), adjusting the port if you changed it:

{
  "mcpServers": {
    "music": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

Restart Claude Desktop. The server must be running before Claude connects — start it first, then open Claude. Ask Claude to compose something.

Module stack

Module	What it provides
music-pitch	Pitches, intervals, enharmonics, tuning
music-time	Durations, time signatures, tempo, metric positions
music-core	Notes, rests, chords, chord symbols, velocity, articulation
music-transform	Transpose, invert, retrograde, augment
music-score	Voice, Part, Score — the central exchange types
music-voice	Voice operations: slice, concat, pad, merge
music-harmony	Keys, scales, Roman numerals, chord progressions, harmonizer
music-instrument	Instrument catalog with ranges and GM program numbers
music-rules	Voice leading, range, meter, parallel motion checks
music-form	Sections, formal plans, volta endings
music-midi	MIDI render and read, General MIDI constants
music-lilypond	LilyPond source generation and PDF engraving
music-mcp	47 MCP tools, composition context, save/load
music-server	HTTP adapter, MCP dispatch, session event log

Build and test

./mvnw test                   # all modules
./mvnw test -pl music-mcp     # just MCP layer

Limitations

music.build is designed for single-user local use. All composition state lives in a single in-process CompositionContext — concurrent requests share the same session. Don't run it as a hosted or multi-user service.

Design

Music types are built on codemodel.build — the same typed attribute system used across the *.build family. Each type carries a set of Traits queryable by the framework. Construction uses static factories (Note.of(...), Voice.of(...)); spelling and arithmetic stay exact throughout.

• Exact rational arithmetic — durations are Fraction, never double
• Null-free — Optional for genuinely absent values
• Immutable — transforms return new instances
• Sealed hierarchies — NoteEvent permits Note, Rest, Chord; pattern matching is exhaustive by construction
• Parse ↔ print — toString() and parse() round-trip losslessly for pitches, intervals, durations

Group ID

build.music · 0.1.0-SNAPSHOT