Sonic Pi MCP

Sonic Pi MCP

适用于 Sonic Pi 的模型上下文协议（MCP）服务。在 LLM 客户端中用自然语言描述音乐；模型会生成 Sonic Pi 代码，本服务再通过 OSC 发送代码。使用 Sonic Pi 中随附的 队列运行器，可在各个乐段之间进行交叉淡化。

功能

• queue_segment — 发送下一个完整乐段（命名的 live_loop、use_bpm 等）。
• run_code — 与 queue_segment 相同（用于兼容）。
• stop_all — 通过 OSC（/stop-all-jobs）硬停止，效果类似 Sonic Pi 的 Stop。
• play_note — 快速测试音符。
• 资源 — DJ 演奏会的创作技巧、词汇和工具用法（从 MCP 客户端读取）。
• 提示词 next_performance_segment — 为更长的演出提供下一段乐曲的构思辅助。
• 环境变量 — OSC_HOST、OSC_PORT、OSC_CODE_PATH、OSC_STOP_ALL_PATH。

前置条件

• Sonic Pi v4.x
• Node.js 18+（npx / node）
• 支持 MCP 的客户端（Cursor、Claude Desktop、支持 MCP 的 VS Code 等）

可选：使用 Bun 进行本地开发（bun run dev）。

Sonic Pi 一次性设置（队列运行器）

1. 打开 Sonic Pi。
2. 将 sonic-pi-queue.rb 复制到一个缓冲区中。
3. 按下 Run 并保持运行。

该缓冲区会监听默认 OSC 端口，并在 MCP 发送的乐段之间进行交叉淡化。

安装 MCP 服务

npx -y sonic-pi-mcp

让客户端通过 stdio 调用此命令（见下文）。

Cursor

使用 ~/.cursor/mcp.json 和/或项目中的 .cursor/mcp.json：

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

本地克隆（运行 npm install 或 bun install 和 bun run build 后）：

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

无需构建直接使用 Bun — 有些客户端会忽略 cwd；请使用 src/server.ts 的绝对路径，或使用启动脚本：

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

运行一次 chmod +x bin/mcp-dev.sh。该脚本会切换到仓库目录并运行 bun run src/server.ts。

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（Windows 上的路径有所不同）：

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

对于本地克隆，如果遇到 Module not found "src/server.ts" 或 spawn bunx ENOENT，建议使用 bin/mcp-dev.sh（见上文）。如果应用缓存了旧配置，请移除 MCP 后重新添加。

VS Code

按照扩展文档，将 MCP 扩展配置为使用 -y 和 sonic-pi-mcp 参数运行 npx，并使用 stdio 传输。

环境变量

变量	默认值	含义
OSC_HOST	127.0.0.1	Sonic Pi 主机
OSC_PORT	4560	Sonic Pi OSC 端口
OSC_CODE_PATH	/run-code	代码的 OSC 路径（必须与 Sonic Pi 缓冲区匹配）
OSC_STOP_ALL_PATH	/stop-all-jobs	硬停止路径

如果从其他机器连接，请在 Sonic Pi 中允许传入 OSC，并相应设置 OSC_HOST。

开发

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 冒烟测试（Sonic Pi 和运行器均已运行）：

bun run test

MCP Inspector

npx @modelcontextprotocol/inspector

构建后（bun run build），使用 node，参数为 bin/cli.mjs，并将此目录设为工作目录。

故障排除

• 没有声音 — Sonic Pi 是否已打开？队列缓冲区是否正在运行？端口 4560 是否可访问？
• 没有任何反应 — Sonic Pi 中是否启用了 OSC；OSC_HOST / OSC_PORT 是否匹配。
• 音轨层不断叠加 — 使用带名称的 live_loop 和 queue_segment；仅在需要完全重置时使用 stop_all。
• Module not found "src/server.ts"（Claude） — 将 bin/mcp-dev.sh 设为 command 并使用空的 args，或使用绝对路径；不要只依赖 cwd。
• resources/list / prompts/list → Method not found — 你使用的是较旧的构建版本，该版本只提供了工具。请从此仓库或 npm 重新安装/重启 MCP，以注册资源和提示词。
• Sonic Pi 日志中出现 Ruby 错误 — 生成的代码解析失败或无法运行；请修正代码片段（括号、采样、语法）后重新发送。队列运行器会在失败时打印代码片段。

许可证

MIT — 参见 LICENSE。