Sonic Pi MCP

Sonic Pi MCP

Servidor Model Context Protocol (MCP) para Sonic Pi. Descreva música em linguagem natural no seu cliente LLM; o modelo gera código Sonic Pi e este servidor o envia via OSC. Use o queue runner incluído no Sonic Pi para crossfades entre segmentos.

Recursos

• queue_segment — envia o próximo segmento musical completo (nomeados live_loops, use_bpm, etc.).
• run_code — igual a queue_segment (compatibilidade).
• stop_all — parada forçada via OSC (/stop-all-jobs), como o Stop do Sonic Pi.
• play_note — nota de teste rápida.
• Resource — técnica de sessão de DJ, vocabulário e uso de ferramentas (lido pelo cliente MCP).
• Prompt next_performance_segment — ajuda a estruturar o próximo bloco para sets mais longos.
• Env — OSC_HOST, OSC_PORT, OSC_CODE_PATH, OSC_STOP_ALL_PATH.

Pré-requisitos

• Sonic Pi v4.x
• Node.js 18+ (npx / node)
• Um cliente compatível com MCP (Cursor, Claude Desktop, VS Code com MCP, etc.)

Opcional: Bun para desenvolvimento local (bun run dev).

Configuração única do Sonic Pi (queue runner)

1. Abra o Sonic Pi.
2. Copie sonic-pi-queue.rb para um buffer.
3. Pressione Run e deixe-o em execução.

O buffer escuta na porta OSC padrão e faz crossfade entre os segmentos enviados pelo MCP.

Instale o servidor MCP

npx -y sonic-pi-mcp

Aponte seu cliente para este comando via stdio (veja abaixo).

Cursor

Use ~/.cursor/mcp.json e/ou .cursor/mcp.json em um projeto:

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

Clone local (após npm install ou bun install e bun run build):

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

Bun sem build — alguns clientes ignoram cwd; use um caminho absoluto para src/server.ts, ou use o launcher:

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

Execute chmod +x bin/mcp-dev.sh uma vez. O script entra no repositório e executa bun run src/server.ts.

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (os caminhos diferem no Windows):

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

Para um clone local, prefira bin/mcp-dev.sh (veja acima) se você vir Module not found "src/server.ts" ou spawn bunx ENOENT. Remova e adicione novamente o MCP no aplicativo se uma definição antiga estiver em cache.

VS Code

Configure sua extensão MCP para executar npx com -y e sonic-pi-mcp, transporte stdio, conforme a documentação da extensão.

Variáveis de ambiente

Variável	Padrão	Significado
OSC_HOST	127.0.0.1	host do Sonic Pi
OSC_PORT	4560	porta OSC do Sonic Pi
OSC_CODE_PATH	/run-code	caminho OSC para código (deve corresponder ao seu buffer do Sonic Pi)
OSC_STOP_ALL_PATH	/stop-all-jobs	caminho de parada forçada

Permita OSC de entrada no Sonic Pi se você conectar de outra máquina; defina OSC_HOST de acordo.

Desenvolvimento

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

Teste rápido de OSC (Sonic Pi + runner em execução):

bun run test

MCP Inspector

npx @modelcontextprotocol/inspector

Use node com o argumento bin/cli.mjs e este diretório como diretório de trabalho (após bun run build).

Solução de problemas

• Sem som — Sonic Pi aberto? Buffer da fila em execução? Porta 4560 acessível?
• Nada acontece — OSC habilitado no Sonic Pi; OSC_HOST / OSC_PORT correspondem.
• Camadas se acumulam — Use queue_segment com live_loops nomeados; use stop_all apenas para um reset completo.
• Module not found "src/server.ts" (Claude) — Use bin/mcp-dev.sh como command com args vazio, ou caminhos absolutos; não confie apenas em cwd.
• resources/list / prompts/list → Method not found — Você está em uma versão mais antiga que só expunha ferramentas. Reinstale/reinicie o MCP deste repositório ou do npm para que recursos e prompts sejam registrados.
• Erros de Ruby no log do Sonic Pi — O código gerado falhou ao analisar ou executar; corrija o trecho (colchetes, samples, sintaxe) e envie novamente. O queue runner imprime um trecho de código em caso de falha.

Licença

MIT — veja LICENSE.