Sonic Pi MCP Server

How to use

Connect an MCP client to the Sonic Pi MCP server. You’ll send tool commands like playing a note or executing Sonic Pi code. Before you send any commands, ensure Sonic Pi is running and the OSC handler is active so messages reach Sonic Pi.

How to install

Prerequisites you need before starting: Bun, Sonic Pi (version 4.0 or higher), and an MCP‑compatible client such as Cursor or Claude Desktop.

Install Bun if you haven’t already, then set up the MCP server locally and run it in development mode.

# 1) Clone the Sonic Pi MCP repository
git clone https://github.com/abhishekjairath/sonic-pi-mcp.git
cd sonic-pi-mcp

# 2) Install Bun if you haven't already
curl -fsSL https://bun.sh/install | bash

# 3) Install dependencies
bun install

# 4) Start the MCP server in development mode
bun run dev

Prepare Sonic Pi to receive OSC messages. In Sonic Pi, create a buffer with the OSC handler and run it so it can execute code sent by the MCP server.

# Required Sonic Pi configuration
# Add this to a buffer in Sonic Pi and run it

live_loop :code_runner do
  use_real_time
  code = sync "/osc*/run-code"
  
  # Since we receive the code as a string, we can use eval to execute it
  # The code comes as the first element of the message
  begin
    eval(code[0].to_s)
  rescue Exception => e
    puts "Error executing code: #{e.message}"
  end
end

Additional setup by client

Two MCP client configurations are shown for local integration. Copy these into your client’s MCP settings to connect to the Sonic Pi MCP server.

{
  "mcpServers": {
    "sonic_pi_mcp": {
      "name": "Sonic Pi MCP",
      "command": "bunx",
      "args": ["sonic-pi-mcp"],
      "transport": {
        "type": "stdio"
      }
    }
  }
}

Security and maintenance notes

Limit access to your MCP endpoints to trusted clients. Regularly update Sonic Pi and the MCP server to benefit from bug fixes and new features. If you change the Sonic Pi OSC handler, recheck that the handler buffer is still running and listening on the default OSC port (4560) or any port you configure.

Troubleshooting

No sound - Ensure Sonic Pi is running. - Confirm the OSC handler code is actively running in Sonic Pi. - Verify Sonic Pi is listening on port 4560 (default).

Connection errors - Check that no other MCP server instance is occupying the stdio channel. - Restart Sonic Pi and then the MCP server. - Ensure the client is configured to use the correct command and arguments shown in the setup steps.

Code execution errors - Check the Sonic Pi log/output window for error messages. - Verify the provided Sonic Pi code is syntactically correct and uses available synths. - Ensure required synths and samples are present in Sonic Pi.

Notes on tools and usage patterns

Available tools let you perform focused actions in Sonic Pi. You can play a single note with customizable synth parameters or execute arbitrary Sonic Pi code to create complex patterns.

play_note

Plays a single note with customizable parameters such as MIDI note number, synth type, sustain, and cutoff.

run_code

Executes arbitrary Sonic Pi code sent from the MCP client, enabling dynamic musical generation.