mainstage-mcp

An MCP server that lets an AI assistant (Claude Desktop, or any other MCP client) build Apple MainStage concerts for you.

Tell your assistant "Add a patch for Jump by Van Halen to my band concert" and it will:

• work out tempo, time signature and the keyboard sounds the song needs,

• pick matching sounds from your installed Logic Pro / MainStage sound library,

• create the patch in your concert with the right tempo, time signature, fader levels, pan and mute,

• optionally add a Playback channel strip with a backing track you point it to.

🇩🇪 Deutsche Anleitung: README.de.md

Unofficial project. MainStage has no public API, so this server edits the concert package on disk. The file format was analysed by comparing files saved by MainStage. Every change is backed up first, and unknown file layouts are rejected instead of being modified. Still: keep your own backups of important concerts.

Features

Related MCP server: Logic Pro MCP Server

Requirements

• macOS with MainStage 3 (concerts saved with MainStage 3.2 or newer)

• The Logic Pro / MainStage sound library (MainStage ▸ Sound Library) for search_sounds

• Python 3.10+ (python3 --version)

• An MCP client, e.g. Claude Desktop

Installation

# 1. create an isolated environment
python3 -m venv ~/.mainstage-mcp

# 2. install the server from GitHub
~/.mainstage-mcp/bin/pip install "git+https://github.com/ChristianLechner304/mainstage-mcp.git"

# 3. check it starts (Ctrl+C to quit)
~/.mainstage-mcp/bin/mainstage-mcp

To update later: ~/.mainstage-mcp/bin/pip install --upgrade "git+https://github.com/ChristianLechner304/mainstage-mcp.git"

Connect it to Claude Desktop

Open Claude Desktop ▸ Settings ▸ Developer ▸ Edit Config and add the server to claude_desktop_config.json (replace YOUR_USER with your macOS user name, echo $HOME shows it):

{
  "mcpServers": {
    "mainstage": {
      "command": "/Users/YOUR_USER/.mainstage-mcp/bin/mainstage-mcp",
      "env": {
        "MAINSTAGE_CONCERTS_DIR": "/Users/YOUR_USER/Music/MainStage"
      }
    }
  }
}

Restart Claude Desktop. The MainStage tools appear in the tools menu of a new chat. Other MCP clients use the same command (stdio transport).

Configuration

All settings are optional environment variables in the env block:

Concerts can always be addressed by full path too, and find_audio_files / add_playback accept any folder or file you mention in the chat. Nothing user-specific is hard-coded.

macOS permissions

• Automation / System Events: to detect whether MainStage has a concert open, the server reads MainStage's window titles. macOS asks once whether Claude may control "System Events"; allow it. Without this permission the server refuses to edit concerts while MainStage is running at all.

• Files: if your concerts or backing tracks live in a protected location (Desktop, Documents, Downloads, iCloud/OneDrive folders), macOS may ask for access the first time.

Working with MainStage

1. Close the concert in MainStage (or quit MainStage) before asking for changes. MainStage keeps the concert in memory and would overwrite the changes when saving. The server checks this and tells the assistant to ask you to close it; with wait_seconds it waits until you have.

2. Ask your assistant, e.g.:

   • "Which patches are in my concert 'Band 2026'?"

   • "I need a flute sound – where can I find one?"

   • "Add a patch for 'Jump' by Van Halen to 'Band 2026': synth brass for the riff, a lead for the solo (muted), faders at 0 dB."

   • "Set the solo lead in 'Jump' to -3 dB and unmute it."

   • "Add the backing track from ~/Music/Backing Tracks for 'Jump' as playback, muted."

3. Open the concert in MainStage. New patches appear at the end of the patch list (or at the requested position) with the next free program change number.

Playback tracks

add_playback copies an existing Playback channel strip and points it to a new audio file, so routing (e.g. Output 3-4), effects and Playback settings follow your usual setup.

One-time setup: create one patch in any concert with a channel strip that uses the Playback plug-in and has an audio file loaded, then save the concert. The server finds it automatically in your concert folder, or you set MAINSTAGE_PLAYBACK_TEMPLATE to that .cst file (inside the concert package: Show Package Contents ▸ Concert.patch ▸ Patch.patch ▸ Channel.cst).

Only use audio files you have the rights to use (purchased backing tracks, your own recordings or stems).

Limitations

• Sounds come from single-channel-strip library patches (≈3,700 in the full library). Multi-strip "summing stack" patches are skipped.

• Plug-in parameters inside a channel strip (e.g. reverb amount, filter cutoff) cannot be edited; choose a fitting preset instead, or create your own library patches and point MAINSTAGE_LIBRARY_DIRS to them.

• Screen-control mappings, keyboard splits/layers and sets (folders) are not created yet. New patches copy the screen-control layout of an existing patch in the concert, so the concert needs at least one patch.

• Tested with MainStage 3 concerts on Apple Silicon. Other versions may use a different file layout; the server then refuses to edit instead of guessing.

How it works

See docs/FORMAT.md for what is known about the concert and channel-strip format.

Development

git clone https://github.com/ChristianLechner304/mainstage-mcp.git
cd mainstage-mcp
python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"
.venv/bin/pytest

Contributions are welcome, especially file-format findings from other MainStage versions. Never commit concerts, channel strips or audio files (Apple sound content and recordings are copyrighted).

License

MIT. MainStage and Logic Pro are trademarks of Apple Inc. This project is not affiliated with Apple.