SuperCollider MCP Server

SuperCollider MCP 服务器

一个用于控制SuperCollider音频合成的模型上下文协议（MCP）服务器。该服务器使像Claude这样的AI助手能够通过自然语言描述生成和控制实时音频合成。

特点/特性

• 自然语言声音合成用通俗易懂的语言描述声音，并实时合成这些声音
• 10种内置合成器类型正弦音、拨弦音、钟声、低音、垫音、底鼓、军鼓、踩镲、氛围音、扫弦
• 服务器生命周期管理启动、退出并监控SuperCollider服务器状态
• 模式序列化创作节奏模式和旋律序列
• 录音将合成输出记录到文件
• 原始代码执行执行自定义的SuperCollider代码以实现高级控制
• TypeScript & 类型安全使用Zod模式进行完全类型化验证

先决条件

• Node.js 18及以上版本
• 本地安装的SuperCollider（在此下载)

安装SuperCollider

macOS:

1. 从 https://supercollider.github.io/downloads 下载
2. 拖拽 SuperCollider.app 到；向；对于；为了 /Applications/
3. MCP服务器将自动检测它

Linux（Ubuntu/Debian）：

sudo apt-get install supercollider

Linux（Arch）：

sudo pacman -S supercollider

Windows：

1. 从 https://supercollider.github.io/downloads 下载安装程序
2. 运行安装程序
3. MCP服务器将自动检测到它

自定义安装路径

如果SuperCollider安装在非标准位置，请设置环境变量：

export SCLANG_PATH="/path/to/sclang"
# Optional: export SCSYNTH_PATH="/path/to/scsynth"

安装

npm install
npm run build

用法

使用Claude Desktop

在你的Claude桌面配置文件中添加：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "supercollider": {
      "command": "node",
      "args": ["/absolute/path/to/supercollider-mcp/dist/index.js"]
    }
  }
}

Windows： %APPDATA%\Claude\claude_desktop_config.json

更新配置后，重启Claude桌面版。

使用MCP Inspector（用于测试）

npm run inspector

独立开发

npm run dev

可用工具

设置与诊断

sc_health_check

检查SuperCollider是否已正确安装和配置。 先运行这个 如果你有任何问题。

// No parameters required
sc_health_check()

返回值：

• ✅ 成功：SuperCollider路径已确认
• ❌ 错误：您的平台安装说明

______________________________________________________________________

核心服务器管理

sc_boot

启动SuperCollider音频服务器。在进行任何声音合成之前必须调用。

// No parameters required
sc_boot()

sc_quit

退出SuperCollider服务器并清理资源。

sc_status

获取当前服务器状态，包括CPU使用率和正在运行的合成器。

______________________________________________________________________

声音合成

sc_play_synth （推荐给AI）

根据自然语言描述播放合成声音。这是声音生成的主要工具。

示例：

• “播放C4音高的铃声”
• “播放2秒低沉的低音”
• “弹奏一段明亮的拨弦乐”
• “播放一段柔和的氛围垫音”
• “play a short snare”可以翻译为“演奏一段简短的铙钹声”。不过，在音乐语境中，更常见的表达可能是“play a short snare roll”或者简化为“play a quick snare”，但根据原句的直接翻译，“演奏一段简短的铙钹声”是准确的译法
• “在3秒内从100Hz扫频到2000Hz”

{
  "description": "play a bell sound at C5 for 2 seconds"
}

解析器理解：

• 音符名称C4，D#5，Bb3，等等。
• 频率440赫兹，880赫兹，等。
• 描述性术语高，低，明亮，深沉，柔和，响亮，短，长
• 合成器类型钟声、低音、垫音、拨奏、底鼓、军鼓、踩镲、扫弦、氛围音效
• 空间术语左，右（用于平移）

sc_play_synth_advanced

使用明确的参数播放特定的合成器，以实现精确控制。

可用的合成器正弦波、拨弦、钟声、低音、垫音、踢鼓、军鼓、踩镲、氛围音、扫弦

{
  "synthName": "bell",
  "freq": 523.25,
  "amp": 0.4,
  "duration": 2,
  "pan": 0.5
}

参数：

• freq频率，单位为赫兹（默认：440）
• amp振幅 0-1（默认值：0.3）
• duration持续时间（以秒为单位）（默认：1）
• pan声像位置 -1（左）到 1（右）（默认：0）
• decay拨弦合成器的衰减时间（默认值：2）
• cutoff低音/延音滤波器截止频率
• startFreq， endFreq用于扫频合成

sc_play_pattern

演奏一个节奏型或一系列音符。

{
  "pattern": [
    { "synth": "kick", "delay": 0 },
    { "synth": "snare", "delay": 0.5 },
    { "synth": "hihat", "delay": 0.25, "amp": 0.2 },
    { "synth": "hihat", "delay": 0.25, "amp": 0.2 },
    { "synth": "kick", "delay": 0.5 }
  ]
}

sc_stop_all

立即停止所有正在播放的合成器声音。

______________________________________________________________________

高级控制

sc_execute

执行原始SuperCollider代码以实现自定义合成和高级控制。

{
  "code": "{ SinOsc.ar([440, 442], 0, 0.2) }.play;"
}

______________________________________________________________________

录音

sc_record_start

开始将音频输出录制到文件中。

{
  "filename": "my-composition.wav"
}

文件保存到 recordings/ 目录。

sc_record_stop

停止当前录音。

______________________________________________________________________

示例对话流程

用户“我想听一听梦幻般的铃声”

克劳德：

Using sc_boot to start SuperCollider server...
Using sc_play_synth with description "bell sound at C5"...

服务器将使用调频合成技术合成一个类似钟声的音调。

用户“现在来演奏一段贝斯线”

克劳德：

Using sc_play_pattern with:
- Low bass notes
- Rhythmic timing

______________________________________________________________________

合成器描述

正弦

纯正弦波音调。清晰简洁。

拨动（弦）

使用卡尔普斯-斯特朗算法模拟拨弦效果。适合模拟吉他音色。

铃

钟形调频合成。明亮且金属质感。

贝斯（或低音提琴）

滤波后的锯齿波。深沉的低音。

平板电脑

温暖、失谐的锯齿波垫音。适合营造环境背景音。

踢

带有频率包络的底鼓。

军鼓（一种打击乐器）

带有噪音和音调成分的军鼓。

踩镲

使用滤波噪声的踩镲镲片。

大气层；气氛

具有慢速滤波器调制的大气噪声。适用于环境纹理。

清扫

频率扫描/上升。在持续时间内从起始频率（startFreq）变化到结束频率（endFreq）。

______________________________________________________________________

建筑学

src/
├── index.ts           # MCP server implementation
├── supercollider.ts   # SuperCollider process management
└── synth-library.ts   # Synth definitions and NLP parser

关键组件：

• SuperCollider服务器管理sclang进程的生命周期和代码执行
• 合成器库为常见声音类型预定义的合成器定义（SynthDefs）
• 自然语言处理解析器将自然语言转换为合成参数
• MCP 工具用于AI交互的公开函数

______________________________________________________________________

与MXF的集成

这台服务器旨在与……配合使用 模型交换框架（MXF） 用于多智能体音乐创作。未来的改进将包括：

• 由MXF事件触发的事件驱动合成
• 用于音乐上下文（音调、节奏、风格）的共享内存
• 与MIDI MCP服务器进行协调以实现外部控制
• 代理在组合任务上的协作

______________________________________________________________________

发展

构建

npm run build

观察模式（用于开发）

npm run dev

类型检查

npx tsc --noEmit

______________________________________________________________________

故障排除

“sclang 未找到”

确保已安装SuperCollider，并且 sclang 在你的 PATH 中：

which sclang  # Should show the path to sclang

在 macOS 上，您可能需要将以下内容添加到您的 PATH 中：

export PATH="/Applications/SuperCollider.app/Contents/MacOS:$PATH"

服务器无法启动

• 检查是否没有其他 SuperCollider 实例正在运行
• 验证SuperCollider能否独立运行： sclang
• 在MCP日志中检查服务器输出

无声音输出

• 验证您的系统音频是否正常工作
• 检查SuperCollider音频设备设置
• 尝试 Server.default.options.device = "your-device-name"; via（在中文中，"via"通常不直接翻译，因为它是一个介词，在句子中根据上下文有不同的翻译方式，但基本意思是“通过”或“经由”。例如，“I sent the file via email”可以翻译为“我通过电子邮件发送了文件”。） sc_execute

______________________________________________________________________

未来的改进/增强功能

• \[ \] 实时参数调制
• \[ \] MIDI输入/输出集成
• \[ \] 样本播放与操作
• \[ \] 效果处理（混响、延迟、滤波器）
• \[ \] 视觉波形/频谱显示
• \[ \] 支持多服务器（超新星）
• \[ \] 预设管理
• \[ \] MXF事件总线集成
• \[ \] 多智能体协作创作

______________________________________________________________________

许可证

麻省理工学院（MIT）

贡献；做出贡献

欢迎贡献！请提出问题或提交拉取请求。