Sonic MCP – Produção de Beats com IA
AJBogo9/sonic-mcp
Crie beats com Claude + Sonic Pi — produção musical assistida por IA
Ver no GitHubServidor MCP que conecta Claude Code ao Sonic Pi, permitindo produção assistida por IA de música eletrônica e beats. Oferece controle completo sobre playback, mixer, gravação e gerenciamento de padrões e canções via interface de código.
Instalação
npx convez-ai AJBogo9/sonic-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Gerar composições eletrônicas inteiras com Claude
- Assistência criativa em produção musical em tempo real
- Automação de tarefas repetitivas de síntese de som
- Gerenciamento de biblioteca de padrões reutilizáveis
Veredito

Ferramenta especializada e bem arquitetada para músicos e produtores que desejam integrar IA generativa no fluxo de criação no Sonic Pi. Requer Linux/Ubuntu e conhecimento técnico de audio e síntese, mas oferece potencial genuíno para workflows experimentais.
README
A tradução para o português deste README ainda está na fila.
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
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
| Tool | Description |
|---|---|
run_code(code) | Run Sonic Pi code |
run_in_buffer(buffer_id, code) | Run code in a specific buffer slot 0-9 |
stop_all() | Stop all playing sounds (including GUI-run buffers) |
get_log(lines) | Read the error log -- call after run_code to catch errors |
Mixer
| Tool | Description |
|---|---|
set_master_volume(amp) | Master amplitude (1.0 = unity, 0.0 = silence, max 5.0) |
mixer_hpf_enable(freq) | Enable master high-pass filter at freq Hz |
mixer_hpf_disable() | Disable master high-pass filter |
mixer_lpf_enable(freq) | Enable master low-pass filter at freq Hz |
mixer_lpf_disable() | Disable master low-pass filter |
mixer_stereo_mode() | Switch master output to stereo |
mixer_mono_mode() | Switch master output to mono |
OSC cues
| Tool | Description |
|---|---|
send_cue(path, value) | Send an OSC cue to trigger a sync in running code |
Song and pattern library
| Tool | Description |
|---|---|
save_song(name, code) | Save a full song (auto-increments version) |
list_songs(name) | List all songs or versions of one song |
load_song(name, version) | Load a song's code (version 0 = latest) |
save_pattern(name, category, code) | Save a reusable snippet |
list_patterns(category) | List patterns, optionally filtered by category |
load_pattern(path) | Load a pattern's code |
Recording
| Tool | Description |
|---|---|
record_start() | Start recording via PipeWire -- returns the output path |
record_stop(output_path) | Stop recording and save to disk |
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): handlesrun_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 triggerssyncpoints 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.
| Script | Description |
|---|---|
sonicpi-headless | Start Sonic Pi without the Qt GUI (PipeWire/JACK audio) |
sonicpi-stop | Stop a headless instance |
sonicpi-status | Show running status, port, and recent log |
Local development
git clone https://github.com/AJBogo9/sonic-mcp.git
cd sonic-mcp
pip install -e .
License
MIT