Sonic Pi MCP

一个模型上下文协议 (MCP) 服务器，允许 AI 助手通过 OSC 消息与 Sonic Pi 交互。这使 Claude 和 Cursor 等 AI 工具能够以编程方式创建音乐和控制 Sonic Pi。

特性

• 播放具有可自定义合成器参数的单个音符
• 执行任意 Sonic Pi 代码
• 适用于任何 MCP 兼容的客户端（Claude Desktop、Cursor 等）

前提条件

• Bun
• Sonic Pi (v4.0 或更高版本)
• 一个 MCP 兼容的客户端（Cursor、Claude Desktop 等）

Sonic Pi 配置

在使用 MCP 服务器之前，您需要将以下代码添加到您的 Sonic Pi 缓冲区。此代码处理服务器发送的 OSC 消息：

# 必需的 Sonic Pi 配置
# 将此添加到 Sonic Pi 中的缓冲区并运行它

live_loop :code_runner do
  use_real_time
  code = sync "/osc*/run-code"
  
  # 由于我们收到的是字符串形式的代码，我们可以使用 eval 来执行它
  # 代码作为消息的第一个元素出现
  begin
    eval(code[0].to_s)
  rescue Exception => e
    puts "Error executing code: #{e.message}"
  end
end

在使用 MCP 服务器之前，请确保此代码在 Sonic Pi 中运行。

与客户端集成

Cursor

添加到 ~/.cursor/mcpServers.json:

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

Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json:

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

可用工具

play_note

播放具有可自定义参数的单个音符。

参数：

• note (必需): MIDI 音符编号 (0-127)
• synth (可选): 要使用的合成器 (例如, ":saw", ":beep", ":prophet")
• sustain (可选): 音符持续时间，以秒为单位 (默认: 1)
• cutoff (可选): 滤波器截止频率 (默认: 100)

示例:

// 使用锯齿波合成器播放中央 C
{
  "name": "play_note",
  "parameters": {
    "note": 60,
    "synth": ":saw",
    "sustain": 0.5,
    "cutoff": 80
  }
}

run_code

执行任意 Sonic Pi 代码。

参数：

• code (必需): 要执行的 Sonic Pi 代码

示例:

{
  "name": "run_code",
  "parameters": {
    "code": "use_synth :prophet\nplay_pattern_timed [60, 64, 67], [0.5]"
  }
}

使用示例

以下是使用 MCP 工具的一些示例交互：

简单旋律

// 播放 C 大调琶音
{
  "code": `
    use_synth :piano
    play_pattern_timed [60, 64, 67, 72], [0.25], release: 0.1
  `
}

复杂模式

// 创建一个节奏模式
{
  "code": `
    live_loop :rhythm do
      use_synth :tb303
      play choose(chord(:C3, :minor)), release: 0.2, cutoff: rrand(60, 120)
      sleep 0.25
    end
  `
}

故障排除

1. 没有声音

   • 确保 Sonic Pi 正在运行
   • 检查 OSC 处理程序代码是否在 Sonic Pi 中运行
   • 验证 Sonic Pi 是否正在监听端口 4560（默认）

2. 连接错误

   • 检查服务器的另一个实例是否正在运行
   • 重新启动 Sonic Pi
   • 确保没有其他应用程序正在使用端口 4560

3. 代码执行错误

   • 检查 Sonic Pi 日志窗口中的错误消息
   • 验证您的 Sonic Pi 代码的语法
   • 确保所有必需的合成器和采样都可用

开发

# 克隆存储库
git clone https://github.com/abhishekjairath/sonic-pi-mcp.git
cd sonic-pi-mcp

# 如果您尚未安装 Bun，请安装它
curl -fsSL https://bun.sh/install | bash

# 安装依赖项
bun install

# 启动 Sonic Pi 并运行 OSC 处理程序代码（请参阅 Sonic Pi 配置部分）

# 在开发模式下启动服务器
bun run dev

使用 MCP Inspector 进行测试

1. 安装并启动 MCP Inspector：

npm install -g @modelcontextprotocol/inspector
mcp-inspector

2. 打开您的浏览器并导航到 http://localhost:3000

3. 在 MCP Inspector UI 中，配置连接：

   • 命令: bun
   • 参数: run src/server.ts
   • 工作目录: /path/to/your/sonic-pi-mcp (使用您的实际项目路径)
   • 传输类型: stdio

4. 测试 play_note 工具:

{
  "name": "play_note",
  "parameters": {
    "note": 60,
    "synth": ":beep",
    "sustain": 0.5
  }
}

5. 测试 run_code 工具:

{
  "name": "run_code",
  "parameters": {
    "code": "use_synth :prophet\nplay_pattern_timed scale(:c4, :major), [0.25]"
  }
}

故障排除开发问题

1. Bun 安装问题

   • 确保 Bun 在您的 PATH 中
   • 尝试运行 bun --version 以验证安装
   • 如果使用 Claude Desktop，请在配置中使用 Bun 的完整路径

2. MCP Inspector 连接问题

   • 验证服务器是否正在运行 (bun run dev)
   • 检查工作目录路径是否正确
   • 确保没有其他服务器实例正在运行

3. OSC 通信问题

   • 确认 Sonic Pi 正在运行并且 OSC 处理程序代码处于活动状态
   • 检查服务器日志中的连接错误
   • 验证端口 4560 是否可用且未被阻止

贡献

1. Fork 存储库
2. 创建您的功能分支 (git checkout -b feature/amazing-feature)
3. 提交您的更改 (git commit -m 'Add some amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 打开一个 Pull Request

许可证

该项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅 LICENSE 文件。