house-mcp
<!-- (C) -->
# house-mcp
An [MCP](https://modelcontextprotocol.io) server that gives an AI assistant two music skills:
listen to a reference track and describe it (tempo, key, a chord vamp to match it, where the
drops and breakdowns are), and write a complete house arrangement as MIDI, one file per
instrument, ready to drop into any DAW.
Ask Claude "make me something like this track" and it can analyze the track, pick the tempo and
key, and hand you a 128-bar arrangement with kick, clap, hats, snare build, bass, chord stabs, pad
and arpeggio.
## Tools
| Tool | What it does |
|---|---|
| `analyze_song(path)` | Reads an `.mp3` or `.wav`. Returns tempo (folded into the 110 to 140 BPM house range), the best key guess with runners-up, a two-chord vamp in that key, the five strongest pitches, and an eight-section energy map. |
| `generate_arrangement(out_dir, bpm, root, mode, arrangement)` | Writes a MIDI pack. `arrangement="loop"` is an 8-bar groove; `"full"` is a 128-bar track in eight sections: intro, groove, breakdown, build, drop, breakdown, groove, outro. |
| `list_pack(out_dir)` | Lists the `.mid` files in a pack with their sizes. |
Bad input (an unknown key, a BPM outside 60 to 200, a missing file) comes back as an
`{"error": ...}` result the model can read and correct, never a crash.
## Quick start
Python 3.10 or newer.
```bash
git clone https://github.com/plutothedev/house-mcp
cd house-mcp
pip install -r requirements.txt
```
**Claude Code:**
```bash
claude mcp add house-mcp -- python /absolute/path/to/house-mcp/server.py
```
**Claude Desktop** (`claude_desktop_config.json`):
```json
{
"mcpServers": {
"house-mcp": {
"command": "python",
"args": ["/absolute/path/to/house-mcp/server.py"]
}
}
}
```
Then try: *"Analyze ~/Music/reference.mp3, then write a full arrangement in the same key and
tempo into ~/Music/house-pack."*
## How the arrangement is built
The harmony is the two-chord vamp deep and melodic house leans on: the i chord (a minor 7th, or a
major 7th in a major key) and a minor 7th a whole step above it, changing every two bars. In G
minor that is Gm7 to Am7.
The full arrangement, by bar:
| Bars | Section | Playing |
|---|---|---|
| 0 to 15 | Intro | Pad, closed hats, a soft kick in bars 12 to 15 |
| 16 to 31 | Groove | Kick, clap, both hats, bass, chord stabs |
| 32 to 47 | Breakdown | Pad and bass |
| 48 to 63 | Build | Bass, busier hats, kick back at bar 56, a snare roll that doubles in speed from bar 56 |
| 64 to 79 | Drop | Kick, clap, both hats, bass, chord stabs, arpeggio |
| 80 to 95 | Breakdown | Pad, with the arpeggio in bars 88 to 95 |
| 96 to 111 | Groove | Kick, clap, both hats, bass, chord stabs |
| 112 to 127 | Outro | Pad, with kick and closed hats until bar 119 |
Drums use General MIDI notes (kick 36, snare 38, clap 39, closed hat 42, open hat 46). The pitched
parts carry notes only: the sound comes from whatever synth or sample you load on each track.
Tempo comes from librosa's beat tracker. Key comes from matching the track's average chroma
against the Krumhansl-Kessler key profiles.
## What it does not do
- It does not control a DAW. FL Studio, for one, has no outside automation API, so the output is
MIDI files you import.
- It matches notes, not sound. The vibe of a track lives in its patches and samples.
- Tempo and key are estimates. Expect the right answer on clear, four-on-the-floor material and
check by ear on anything else.
## Layout
```
server.py entry point (python server.py)
house_mcp/
server.py the three MCP tools
arrangement.py builds every part as note events, no I/O
midi.py writes a part to a .mid file
analysis.py tempo, key, vamp and energy map
theory.py note names, MIDI numbers, chord shapes, key profiles
tests/ pytest suite
```
## Development
```bash
pip install -r requirements.txt pytest
python -m pytest
```
The suite covers:
- **Golden digests:** every case's MIDI messages are hashed in `tests/golden.json`, so any change
to the generated notes fails. For an intended change, run `python -m tests.golden` and review
the diff.
- **Musical checks:** chord spellings, every note released, notes inside the song, tempo written
to every file.
- **Analysis:** tempo, key and energy map checked on synthetic tracks generated inside the tests.
- **A real MCP round trip:** a client starts `server.py` over stdio, lists the tools and calls one.
## License
MIT. See [LICENSE](LICENSE).
TDQS
Scored across 3 tools
Each tool has a clearly distinct purpose: analyze_song reads audio, generate_arrangement writes MIDI, list_pack inspects output folders. No overlap in resource or action, so misselection is unlikely.
All three tools follow a consistent snake_case verb_noun pattern: analyze_song, generate_arrangement, list_pack. Tense and style are uniform throughout.
Three tools is on the thin side but fits a narrow analyze→generate→inspect workflow without bloat. Each tool earns its place, though one or two more (e.g. regenerate/validate) would round it out.
Core happy path (analyze reference → generate pack → list files) is covered, but the surface has dead ends: no delete/cleanup, no inspecting individual .mid contents, and no way to modify or regenerate a section of an existing arrangement.