Sonic Pi 服务器

Name: Sonic Pi 服务器
Author: abhishekjairath

作者：abhishekjairath8 星标更新：2025-06-22

安装使用来源：spider==github.com

项目介绍

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 "执行代码时出错：#{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
  `
}

故障排除

没有声音
- 确保Sonic Pi正在运行
- 检查Sonic Pi中的OSC处理器代码是否在运行
- 确认Sonic Pi正在监听默认端口4560
连接错误
- 检查是否有其他实例的服务器正在运行
- 重新启动Sonic Pi
- 确保没有其他应用程序占用端口4560
代码执行错误
- 检查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测试

安装并启动MCP Inspector：

npm install -g @modelcontextprotocol/inspector
mcp-inspector

打开浏览器并导航至http://localhost:3000
在MCP Inspector UI中配置连接：
- 命令：bun
- 参数：run src/server.ts
- 工作目录：/path/to/your/sonic-pi-mcp（使用实际项目路径）
- 传输类型：stdio
测试play_note工具：

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

测试run_code工具：

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

开发问题故障排除

Bun安装问题
- 确保Bun已添加到PATH中
- 尝试运行bun --version以验证安装
- 如果使用Claude Desktop，请在配置中使用Bun的完整路径
MCP Inspector连接问题
- 确认服务器正在运行（bun run dev）
- 检查工作目录路径是否正确
- 确保没有其他实例的服务器正在运行
OSC通信问题
- 确认Sonic Pi正在运行且OSC处理器代码处于活动状态
- 检查服务器日志以查找连接错误
- 确认端口4560可用且未被阻塞

贡献

分叉仓库
创建您的功能分支（git checkout -b feature/amazing-feature）
提交更改（git commit -m '添加一些惊人的功能'）
推送到分支（git push origin feature/amazing-feature）
打开Pull Request

许可证

本项目采用MIT许可证 - 查看LICENSE文件以获取详细信息。