ireal-mcp

Builds piano-friendly iReal Pro chord charts — laid out at a fixed 4 measures per line, the way a player reads them off the stand. It produces a tappable irealb:// import link, a standalone HTML chart, a harmonic analysis (Roman numerals + chord-scales + jam plan), and an ASCII layout preview.

Just want to make charts? (no install)

Open ireal-studio.html in any web browser (double-click it). Type a song, press Make chart, and tap Open in iReal Pro on your phone/iPad. It's one self-contained file — works offline, nothing to install, no server, your charts never leave the page.

Don't have the file yet? Run npm run build:web once (or double-click setup.command on a Mac) to produce dist-web/ireal-studio.html, then share/keep that single file.

The rest of this README is for the Claude (MCP) integration and the optional always-on LAN server — power-user routes. On a Mac you can just double-click setup.command, which installs everything and prints exactly what to paste into Claude.

Why "4 measures per line"?

iReal Pro lays a chart out as a grid of 16 cells per line; a chord or a space takes one cell, while barlines, time signatures, rehearsal marks and staff text are free. Left alone, the app packs measures of differing widths and the line breaks wander.

This server makes the layout deterministic: every measure is padded to exactly 16 / measuresPerLine cells (4 cells with the default 4 measures/line), so the app always wraps where you expect. The result reads like a clean fake-book page. You can change the density with measuresPerLine (must divide 16: 1, 2, 4, 8, 16).

Install the MCP server (Mac / Windows / Linux, any MCP client)

The server is plain Node + stdio + the official MCP SDK, so it runs anywhere Node runs and works with any MCP client that supports stdio servers (Claude Code, Claude Desktop, Cursor, Windsurf, …).

Once published to npm (see "Publishing" below), no clone or build is needed — point any client at npx. This config is identical on every OS:

{
  "mcpServers": {
    "ireal": { "command": "npx", "args": ["-y", "ireal-mcp"] }
  }
}

Claude Code: claude mcp add ireal -- npx -y ireal-mcp (the -- is required so the flags go to npx, not to claude).

From source (until it's on npm) — same on all three OSes:

git clone <repo> && cd ireal-mcp
npm install            # runs the build automatically (prepare script)

Then point your client at the absolute path:

{ "mcpServers": { "ireal": { "command": "node", "args": ["/abs/path/ireal-mcp/dist/index.js"] } } }

Or via the CLI (note the -- before the command): claude mcp add ireal -- node /abs/path/ireal-mcp/dist/index.js

Mac shortcut: double-click setup.command — it installs, builds, and prints the exact config. (Windows/Linux: use the git clone steps above; a one-click installer for those is a TODO. The optional always-on LAN server's auto-start is currently Mac-only via launchd — on Windows/Linux run npm run serve manually, or wire it to Task Scheduler / systemd.)

Publishing (to enable npx install everywhere)

npm publish ships the built dist/ (the prepare script builds it; prepublishOnly runs typecheck + tests first). After that, anyone on any OS installs via the npx config above — no clone, no build.

Serve over your network

The companion HTTP server makes every saved chart reachable from other devices (your iPad/phone with iReal Pro) at a stable address:

npm run serve          # binds 0.0.0.0:1357, prints the LAN URLs to use

It reads the chart library on disk per request, so charts the MCP tools save appear immediately. On startup it prints something like:

ireal-mcp HTTP server listening on port 1357
Reachable at:
  http://192.168.68.73:1357
  http://your-mac.local:1357

Open that URL on a device with iReal Pro and tap import to load a chart.

Route	Purpose
/	Index of every chart + "open all as one iReal Pro playlist"
/chart/<slug>	View a chart (layout preview + import button)
/import/<slug>	Redirects straight to the irealb:// import (tap to import)
/playlist	Redirects to an irealb:// playlist of the whole library

Config (env vars): IREAL_PORT (default 1357), IREAL_LIBRARY (default ~/.ireal-mcp/charts).

Keep it running (auto-start on login)

npm run install-service   # writes & loads a launchd LaunchAgent (macOS)

This installs ~/Library/LaunchAgents/com.ireal-mcp.server.plist with KeepAlive so the server starts at login and restarts if it dies. Logs go to ~/.ireal-mcp/server.log. To preview the plist without installing: node scripts/gen-launchd.mjs. To remove: launchctl unload ~/Library/LaunchAgents/com.ireal-mcp.server.plist.

Configure your MCP client

Add to your client config (Claude Desktop / Claude Code .mcp.json, etc.):

{
  "mcpServers": {
    "ireal": {
      "command": "node",
      "args": ["/absolute/path/to/ireal-mcp/dist/index.js"]
    }
  }
}

Or run directly with npx ireal-mcp once published.

Tools

Tool	What it does
create_chart	Build a chart from structured measures (or a raw progression). Saves to the library and serves it over HTTP by default (save: false to skip; slug to control the URL). Returns the modern irealb:// link, legacy link, the served URLs, ASCII preview, raw progression, and warnings. outputHtmlPath also writes a standalone HTML copy anywhere.
preview_chart	ASCII layout grid only — fast iteration while writing chords (no save).
list_charts	List saved charts with their slugs and served URLs.
delete_chart	Remove a chart from the library by slug.
server_info	Report the library path, port, and LAN URLs where the server is reachable, plus the start command.
decode_chart	Parse an existing irealb:///irealbook:// URL (or HTML containing one) back into title/composer/style/key + a measure list, for editing.
list_styles	The built-in iReal Pro styles (Jazz / Latin / Pop).
list_chord_qualities	Valid chord roots, qualities, keys, and time signatures, so generated charts use legal symbols.

Input model

A chart is title + optional composer/style/key/bpm/timeSignature/measuresPerLine, plus either:

• measures (preferred): an array where each measure is { chords: ["A-7","D7"], section?, open?, close?, ending?, staffText?, noChord?, ... }. The server owns the layout and encoding.
• raw: a raw iReal Pro progression string, used verbatim (power users).

Example

A 12-bar B♭ blues:

{
  "title": "Blues for Probe",
  "composer": "Chris Farrell",
  "style": "Medium Swing",
  "key": "Bb",
  "measures": [
    {"chords": ["Bb7"]}, {"chords": ["Eb7"]}, {"chords": ["Bb7"]}, {"chords": ["Bb7"]},
    {"chords": ["Eb7"]}, {"chords": ["Eb7"]}, {"chords": ["Bb7"]}, {"chords": ["G7"]},
    {"chords": ["C-7"]}, {"chords": ["F7"]}, {"chords": ["Bb7","G7"]}, {"chords": ["C-7","F7"]}
  ]
}

Produces:

| Bb7      | Eb7      | Bb7      | Bb7      |
| Eb7      | Eb7      | Bb7      | G7       |
| C-7      | F7       | Bb7  G7  | C-7  F7  |

Chord syntax

Root + quality + optional /bass: C, C-7, C^7, C7b9, C-7/Bb. Alternate chords in parentheses: (Db^7). No chord: use "noChord": true. Custom/free-text qualities: wrap in asterisks, e.g. C*lyd*. Call list_chord_qualities for the full vocabulary.

Sections, repeats, endings

{"chords": ["C^7"], "section": "A", "open": "{"}   // start an A section + repeat
{"chords": ["G7"], "ending": 1, "close": "}"}      // first ending, close repeat
{"chords": ["G7"], "staffText": "D.C. al Coda", "coda": true}

How it works

• obfuscate.ts — port of the irealb:// scrambling (magic prefix 1r34LbKcu7 + literal substitutions + the symmetric 50-byte "hussle"). Verified against the published reference vector and round-tripped.
• layout.ts — distributes each measure's chords across the fixed cell budget (1/2/4 chords map cleanly; dense measures comma-pack at small size) and assembles the progression with barlines, sections, time signatures and endings.
• url.ts — builds and parses both URL schemes (10-field modern, 6-field legacy), composer/title sort-ordering, percent-encoding.
• render.ts — ASCII grid + standalone HTML.

Development

npm test         # vitest: obfuscation vectors, layout cell-counts, URL round-trips
npm run typecheck
npm run dev      # run from source with tsx

Credits

Format details from the iReal Pro custom-URL protocol and the reference implementations under docs/ (pyrealpro, Data::iRealPro, musicxml-irealpro).

License

MIT