Ableton Control Deck

Ableton Control Deck 是一个本地的 MCP 桥接工具，适用于 Ableton Live。它允许任何 MCP 客户端（Claude Code、Claude Desktop、Codex，以及其他支持 MCP 的工具）对 Live 的音轨、片段、传输控制、设备及第三方插件参数进行精确且经过回读验证的控制，同时提供一个本地状态仪表盘。

所有内容均在本地运行，仅绑定到回环地址。不会向网络发布或暴露任何内容。

Ableton 和 Ableton Live 是 Ableton AG 的商标。本项目是一个独立的社区工具，与 Ableton 无关，也未获得其认可。

工作原理

• 一个 Live 远程脚本（remote-script/Control_Deck/）作为控制界面在 Ableton Live 内部运行，监听 UDP 端口 50711，接收经过身份验证的本地请求协议。它暴露的 Live API 是一个明确的允许列表，而非通用的方法执行器。

• MCP 服务器（src/index.ts，编译至 dist/）将 Live 控制暴露为 MCP 工具，并通过一个无依赖的本地 UDP 客户端（src/ableton-client.ts）与远程脚本通信。

• 每次安装都会生成一个唯一的密钥，由 npm run setup 创建，且不会提交到版本控制中，用于验证两者之间的每一个请求。

• 一个只读状态服务（src/dashboard-server.mjs，端口 50712）和一个 Next.js 仪表盘（dashboard/，端口 50713）显示桥接健康状态、当前 Live 会话、加载的设备，以及一个可搜索的本地 VST3、VST2、Audio Unit 和 CLAP 插件库存。

• 一个可选的 Max for Live 设备，Control Deck OmniHost（max-for-live/），直接托管一个 VST3 乐器，并通过其自己的回环通道（UDP 50714）暴露其完整的已发布参数目录（数千个参数，远超 Live 自动设备面板的范围）。

• 一个可选的本地 macOS 封装程序（macos/）将仪表盘显示在一个锁定到本地地址的 WebKit 窗口中；外部导航将被阻止。

• 一个可选的本地 SQLite 样本索引（src/sample-index.ts）使得可以通过关键词、BPM、调性和单拍/循环类型对外部样本驱动器进行搜索，而无需写入源音频。

Related MCP server: io.github.peterkolbe/ableton-for-ai

设计规则

• 轨音轨和设备的修改需要同时提供索引和精确的当前名称；过时的名称将被拒绝。

• 插件加载通过 Live 自身的浏览器索引进行解析，并在名称不明确时拒绝猜测。

• 破坏性操作（delete_track、索引重建）需要明确的确认标志。

• 每次修改后都会执行一次独立的回读查询，工具会报告 Live 实际显示的值。

• 已完成请求的 ID 由桥接器缓存，因此重复的 UDP 请求绝不会执行两次修改。

工具

• 状态、传输控制、速度、拍号及歌曲位置，并附带回读验证

• 列列、创建、重命名和安全删除音轨

• 创建 Session View MIDI 片段并写入经过验证的音符内容

• 检查场景、片段、选区、设备以及 Live 暴露的每一个参数

• 通过 Live 浏览器在特定音轨上发现、解析和加载 VST3/VST2/AU 插件

• 按精确的浏览器名称加载原生 Live 设备（Drum Rack、Echo、Reverb 等），并在名称不明确时拒绝

• 使用标准化值和回读功能读取和设置第三方插件参数

• 通过 OmniHost 控制一个完全索引的 VST3 乐器，突破 Live 的参数上限

• 按关键词、文件夹、BPM、调性、时长和标签搜索本地样本索引

系统要求

• macOS 13 Ventura 或更新版本（Apple 芯片和 Intel）——macOS 是目前唯一支持的平台。核心代码是平台中立的，Linux/Windows 移植范围明确；请参阅 PORTING.md。

• Ableton Live 11 或更新版本（测试目标：Live 12）

• Node.js 20+

• Max for Live（可选——仅用于 OmniHost 设备）

完整文档——包括组件说明、Live 设置、完整的 MCP 工具参考、故障排除和卸载——位于 HELP.md。

安装

快速入门（无需编码）

1. 安装 Node.js ——从 nodejs.org 下载 LTS 版本并使用默认选项运行其安装程序。（Control Deck 依赖它运行；之后您无需再接触它。）

2. 下载 Control Deck ——使用 GitHub 的绿色 Code → Download ZIP 按钮，解压缩，并将文件夹移动到某个永久位置，例如您的用户文件夹。不要将其留在“下载”文件夹中——安装程序会将服务固定到该文件夹的位置，如果移动它会要求您重新操作。

3. 运行安装程序 ——右键单击 Install Ableton Control Deck.command 并选择 打开（macOS 对于首次运行的下载文件需要右键点击）。它会安装所有内容，启动后台服务，并在完成后打开连接指南。随时可以安全地重新运行。

4. 在 Live 中启用控制界面 ——设置 → Link, Tempo & MIDI → 在一个空的控制界面槽位中选择 Control Deck（如果在设置时 Live 已打开，请先重启 Live）。

5. 连接您的 AI 代理 ——打开的指南页面（http://127.0.0.1:50713/connect）为每种客户端提供了复制粘贴的说明。

开发者设置

npm run setup 与安装程序使用的引擎相同——包括依赖安装、TypeScript + OmniHost + 仪表盘构建、每次安装密钥、远程脚本安装以及 launchd 代理的写入和激活。它是幂等的；在拉取更新或移动仓库后重新运行即可。

npm run setup

用于更紧密循环的标志：--skip-build（跳过 npm 安装/构建）、--skip-remote-script、--skip-agents。各个部分仍然可以作为单独的脚本使用（build、build:omnihost、install:omnihost、index:plugins、samples:index，以及仪表盘自身的 dev/build/check）。

设置管理的内容：

1. 一个每次安装的密钥，位于 data/bridge-token（由远程脚本和客户端共享；绝不提交），

2. 远程脚本（已注入密钥）位于 ~/Music/Ableton/User Library/Remote Scripts/Control_Deck/，

3. 两个指向此仓库的 launchd 代理：com.abletondeck.api 和 com.abletondeck.dashboard。

然后将 MCP 服务器添加到您的客户端。例如，对于 Claude Code：

claude mcp add ableton -- node /path/to/ableton-control-deck/dist/src/index.js

在 Live 中，打开 Settings → Link, Tempo & MIDI 并确认 Control Deck 已作为控制界面被选中。

连接其他代理

仪表盘的 Connect 页面（http://127.0.0.1:50713/connect）提供了复制粘贴的设置指南——使用您机器的实际安装路径渲染——适用于 Claude Code、Claude Desktop、Codex、Cursor、VS Code、Windsurf、Gemini CLI、Grok CLI、纯本地 LLM 工具（LM Studio、Ollama 通过 mcphost）以及任何其他 MCP 客户端。此外，还诚实地讨论了将桥接器暴露给远程连接器（如 claude.ai）所需的工作和（安全方面的）代价。简而言之：任何能够启动 stdio MCP 服务器的代理都可以驱动 Live；远程云连接器被有意排除在范围之外。

Control Deck 仪表盘

在 http://127.0.0.1:50713 打开仪表盘（如果您已激活 launch 代理，它会在登录时启动）。它显示桥接健康状态、当前 Live 会话、选定音轨的设备链，以及一个可搜索的本地已安装插件库存。其设置页面控制桥接连接、刷新行为、库默认值、密度、颜色和动效。项目更改仍使用精确、经过回读验证的 MCP 工具。

可选的本地应用程序通过 npm run build:macos 构建为 Ableton Control Deck.app。

本地命令

npm run check          # type-check + syntax-check all sources
npm test               # unit tests (client, tools, validation, safety)
npm run test:bridge    # remote-script protocol tests (Python)
npm run index:plugins  # rebuild the local plug-in inventory
npm run samples:index  # refresh the sample index
npm run build:macos    # build the native wrapper app

仪表盘有自己的构建检查：

cd dashboard
npm run check

安全模型

• 桥接器仅在 127.0.0.1 UDP 50711 上监听；状态服务、仪表盘和 OmniHost 都仅绑定到回环地址。

• 每个桥接请求必须携带来自 data/bridge-token 的每次安装密钥。远程脚本在密钥未被注入时拒绝启动。

• Live API 表面是一个具有精确目标保护措施的明确允许列表，因此混乱的代理会大声失败，而不是编辑错误的内容。

• MCP 服务器将请求本地记录到 logs/control-deck.jsonl，以便您审计代理的操作。

许可证

MIT