Sonic Pi MCP

Model Context Protocol (MCP) server for **Sonic Pi. Describe music in natural language in your LLM client; the model generates Sonic Pi code and this server sends it over OSC. Use the included queue runner** in Sonic Pi for crossfades between segments.

Features

• `queue_segment` — send the next full musical segment (named `live_loop`s, `use_bpm`, etc.).
• `run_code` — same as `queue_segment` (compatibility).
• `stop_all` — hard stop via OSC (`/stop-all-jobs`), like Sonic Pi’s Stop.
• `play_note` — quick test note.
• Resource — DJ session craft, vocabulary, and tool usage (read from the MCP client).
• Prompt `next_performance_segment` — help frame the next block for longer sets.
• Env — `OSC_HOST`, `OSC_PORT`, `OSC_CODE_PATH`, `OSC_STOP_ALL_PATH`.

Prerequisites

• Sonic Pi v4.x
• Node.js 18+ (`npx` / `node`)
• An MCP-capable client (Cursor, Claude Desktop, VS Code with MCP, etc.)

Optional: Bun for local development (`bun run dev`).

One-time Sonic Pi setup (queue runner)

1. Open Sonic Pi.

2. Copy **sonic-pi-queue.rb** into a buffer.

3. Press Run and leave it running.

The buffer listens on the default OSC port and crossfades between segments sent by the MCP.

Install the MCP server

npx -y sonic-pi-mcp

Point your client at this command over stdio (see below).

Cursor

Use `~/.cursor/mcp.json` and/or `.cursor/mcp.json` in a project:

{
  "mcpServers": {
    "sonic_pi_mcp": {
      "command": "npx",
      "args": ["-y", "sonic-pi-mcp"]
    }
  }
}

Local clone (after `npm install` or `bun install` and `bun run build`):

{
  "mcpServers": {
    "sonic_pi_mcp": {
      "command": "node",
      "args": ["/absolute/path/to/sonic-pi-mcp/bin/cli.mjs"]
    }
  }
}

Bun without building — some clients ignore `cwd`; use an absolute path to `src/server.ts`, or use the launcher:

{
  "mcpServers": {
    "sonic_pi_mcp": {
      "command": "/absolute/path/to/sonic-pi-mcp/bin/mcp-dev.sh",
      "args": []
    }
  }
}

Run `chmod +x bin/mcp-dev.sh` once. The script changes into the repo and runs `bun run src/server.ts`.

Claude Desktop

`~/Library/Application Support/Claude/claude_desktop_config.json` (paths differ on Windows):

{
  "mcpServers": {
    "sonic_pi_mcp": {
      "command": "npx",
      "args": ["-y", "sonic-pi-mcp"]
    }
  }
}

For a local clone, prefer `bin/mcp-dev.sh` (see above) if you see `Module not found "src/server.ts"` or `spawn bunx ENOENT`. Remove and re-add the MCP in the app if an old definition is cached.

VS Code

Configure your MCP extension to run `npx` with `-y` and `sonic-pi-mcp`, stdio transport, per the extension’s docs.

Environment variables

Allow incoming OSC in Sonic Pi if you connect from another machine; set `OSC_HOST` accordingly.

Development

git clone https://github.com/abhishekjairath/sonic-pi-mcp.git
cd sonic-pi-mcp
bun install   # or npm install
bun run build
bun run dev

OSC smoke test (Sonic Pi + runner running):

bun run test

MCP Inspector

npx @modelcontextprotocol/inspector

Use `node` with argument `bin/cli.mjs` and this directory as the working directory (after `bun run build`).

Troubleshooting

• No sound — Sonic Pi open? Queue buffer running? Port 4560 reachable?
• Nothing happens — OSC enabled in Sonic Pi; `OSC_HOST` / `OSC_PORT` match.
• Layers pile up — Use `queue_segment` with named `live_loop`s; use `stop_all` only for a full reset.
• `Module not found "src/server.ts"` (Claude) — Use `bin/mcp-dev.sh` as `command` with empty `args`, or absolute paths; don’t rely on `cwd` alone.
• `resources/list` / `prompts/list` → Method not found — You’re on an older build that only exposed tools. Reinstall/restart the MCP from this repo or npm so resources and prompts are registered.
• Ruby errors in Sonic Pi log — The generated code failed to parse or run; fix the snippet (brackets, samples, syntax) and send again. The queue runner prints a code snippet on failure.

License

MIT — see LICENSE.