sonic-mcp

MCP server that connects Claude Code to Sonic Pi for AI-assisted beat making.

Requirements

• Sonic Pi 3.x installed (tested on 3.2.2)

• Ubuntu 24.04 with PipeWire audio (other Linux distros may work)

• uv (recommended) or pip

Related MCP server: FL Studio MCP

Setup

1. Add to Claude Code

Add this to ~/.claude/mcp.json for global use, or a project's .mcp.json to keep it scoped:

{
  "mcpServers": {
    "sonic-pi": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/AJBogo9/sonic-mcp.git", "sonic-mcp"],
      "env": {
        "SONIC_PI_SONGS_DIR": "/home/yourname/songs",
        "SONIC_PI_PATTERNS_DIR": "/home/yourname/patterns"
      }
    }
  }
}

SONIC_PI_SONGS_DIR defaults to ~/songs and SONIC_PI_PATTERNS_DIR defaults to ~/patterns.

2. Start Sonic Pi

Headless (recommended): no GUI required.

# Install the helper scripts once
cp scripts/sonicpi-headless scripts/sonicpi-stop scripts/sonicpi-status ~/.local/bin/
chmod +x ~/.local/bin/sonicpi-headless ~/.local/bin/sonicpi-stop ~/.local/bin/sonicpi-status

# Start / stop
sonicpi-headless
sonicpi-stop
sonicpi-status

Qt GUI (alternative): use pw-jack sonic-pi on PipeWire systems. The desktop shortcut fails to open the audio device on Ubuntu 24.04.

No listener buffer or manual setup is needed in either case. The MCP server connects directly to Sonic Pi's Spider server and auto-discovers the port from the boot log.

Tools

Playback

Mixer

OSC cues

Song and pattern library

Recording

How it works

The MCP server sends OSC messages over UDP to two endpoints:

• Spider server (port discovered from ~/.sonic-pi/log/server-output.log): handles run_code, stop_all, run_in_buffer, and all mixer controls. The Qt GUI uses a dynamically allocated port (around 51235); headless mode uses fixed port 4557.

• Erlang OSC cues port (fixed UDP 4560): handles send_cue, which triggers sync points in running Sonic Pi code.

get_log reads ~/.sonic-pi/log/server-errors.log, which captures runtime errors from evaluated code. Calling it after run_code lets Claude catch and fix errors automatically.

Scripts

See scripts/ for the headless management scripts.

Local development

git clone https://github.com/AJBogo9/sonic-mcp.git
cd sonic-mcp
pip install -e .

License

MIT