sonic-pi-mcp

sonic-pi-mcp is a Python MCP server that lets an MCP client control a local Sonic Pi runtime over the standard stdio transport.

It starts Sonic Pi's Ruby daemon, sends OSC messages to the Spider runtime, runs Sonic Pi code, stops jobs, reads runtime events/logs, and searches the local Sonic Pi docs/samples/synthdefs.

Requirements

• Python 3.11+
• A local Sonic Pi installation or checkout.
• The Sonic Pi root directory must contain:
  • app/server/ruby/bin/daemon.rb
  • app/server/ruby/bin/spider-server.rb
  • usually etc/doc, etc/samples, and etc/synthdefs

No machine-specific path is baked into this package. Set SONIC_PI_ROOT in the MCP client environment unless you pass root_path to sonic_start.

Install

From PyPI:

pip install sonic-pi-mcp

From a local checkout:

pip install .

Build a wheel/sdist:

python -m build

Then install the wheel on another machine:

pip install dist/sonic_pi_mcp-*.whl

The wheel only contains the Python package under src/sonic_pi_mcp. Generated runtime files, exported audio, examples, tests, and local scripts are excluded from distribution.

Configuration

Required in most deployments:

SONIC_PI_ROOT=<path to the Sonic Pi root directory>

Useful optional variables:

SONIC_PI_MCP_RUNTIME_DIR=<writable directory for temporary run_file buffers>
SONIC_PI_MCP_STARTUP_TIMEOUT=60
SONIC_PI_MCP_KEEPALIVE_INTERVAL=4
SONIC_PI_MCP_EVENT_BUFFER_SIZE=5000
SONIC_PI_MCP_DEFAULT_COLLECT_MS=1500
SONIC_PI_HOME=<custom Sonic Pi user-home root for logs, if needed>

SONIC_PI_MCP_RUNTIME_DIR is used when code is too large for Sonic Pi's OSC packet size and must be submitted with run_file. If it is not set, the server uses a per-user cache directory such as %LOCALAPPDATA%\sonic-pi-mcp on Windows, ~/Library/Caches/sonic-pi-mcp on macOS, or ${XDG_CACHE_HOME:-~/.cache}/sonic-pi-mcp on Linux.

PowerShell example without hard-coding a drive:

$env:SONIC_PI_ROOT = Join-Path $env:ProgramFiles 'Sonic Pi'
$env:SONIC_PI_MCP_RUNTIME_DIR = Join-Path $env:LOCALAPPDATA 'sonic-pi-mcp'
sonic-pi-mcp

POSIX shell example:

export SONIC_PI_ROOT="$HOME/apps/sonic-pi"
export SONIC_PI_MCP_RUNTIME_DIR="${XDG_CACHE_HOME:-$HOME/.cache}/sonic-pi-mcp"
sonic-pi-mcp

MCP Client Setup

This package is a stdio MCP server. Configure clients to run the installed console command sonic-pi-mcp.

Generic MCP JSON shape:

{
  "mcpServers": {
    "sonic-pi": {
      "command": "sonic-pi-mcp",
      "args": [],
      "env": {
        "SONIC_PI_ROOT": "<path to Sonic Pi root>",
        "SONIC_PI_MCP_RUNTIME_DIR": "<writable runtime directory>"
      }
    }
  }
}

If your client does not inherit shell environment variables, put the variables in the client config. Avoid relying on the terminal profile of the user who installed the package.

If startup fails, the error includes preflight results, recent daemon output, Sonic Pi log tails, and likely fixes for common path, permission, and audio backend issues.

Run Manually

python -m sonic_pi_mcp

or:

sonic-pi-mcp

Both commands run the same stdio MCP server. They do not open an HTTP port.

MCP Tools

• sonic_start(root_path?, no_inputs?)
• sonic_status()
• sonic_preflight(root_path?)
• sonic_run_code(code, buffer_name?, collect_ms?)
• sonic_play_file(path, buffer_name?, collect_ms?)
• sonic_start_recording(collect_ms?)
• sonic_stop_recording(collect_ms?)
• sonic_save_recording(output_path, collect_ms?, wait_timeout?)
• sonic_delete_recording(collect_ms?)
• sonic_record_file(path, output_path, duration_seconds, bit_depth?, buffer_name?, root_path?, no_inputs?, overwrite?, shutdown_after?, save_timeout?)
• sonic_stop(collect_ms?)
• sonic_shutdown()
• sonic_read_events(since?, limit?)
• sonic_get_logs(source?, tail?)
• sonic_send_cue(path, args?)
• sonic_search_docs(query, limit?, root_path?)
• sonic_list_samples(limit?, root_path?)
• sonic_list_synths(limit?, root_path?)
• sonic_list_fx(limit?, root_path?)

Suggested Agent Workflow

1. Call sonic_preflight() when setting up a new machine or after a boot failure.
2. Call sonic_start(no_inputs=true) unless the user needs audio input.
3. Call sonic_status() and confirm state is ready.
4. Use sonic_search_docs, sonic_list_samples, sonic_list_synths, and sonic_list_fx to stay within the user's installed Sonic Pi version.
5. Send music with sonic_run_code(code, buffer_name, collect_ms) or run a local .rb file with sonic_play_file(path, buffer_name, collect_ms).
6. Export a fixed-duration WAV with sonic_record_file(path, output_path, duration_seconds, bit_depth=24) when the user asks for a rendered file.
7. Inspect returned events for syntax_error, runtime_error, or missing Defining fn :live_loop_... messages.
8. Call sonic_stop() before replacing a long-running composition.
9. Call sonic_shutdown() when the session is no longer needed.

Security

sonic_run_code executes local Sonic Pi code through the same token-protected Spider API used by the Sonic Pi GUI. Treat access to this MCP server as local code execution and local audio-device control.

License

MIT License. You may use, copy, modify, publish, distribute, sublicense, and sell copies of this package, provided the license text is included.

Packaging Notes

The package is intentionally path-neutral:

• No repository-local absolute path is embedded.
• SONIC_PI_ROOT or the root_path tool argument identifies Sonic Pi.
• SONIC_PI_MCP_RUNTIME_DIR controls where temporary large-buffer files are written.
• Build configuration excludes generated files such as .runtime/, exports/, examples, tests, and local playback/export scripts.