Ableton MCP Server

ableton-mcp-server

:globe_with_meridians: Live 落地页与交互式 97 工具目录 · 架构图 · Agent 操作手册 · 工具索引

这是一个开源的 Model Context Protocol（MCP） 服务，可让 AI Agent（Antigravity、Gemini、Codex）和音频开发者查询、分析、操控并自动化运行中的 Ableton Live 12 工程。

当前工具集包含 97 个工具，支持 TCP、WebSockets、组合路由和本地执行（主要通过 device_name、track_index 和 clip_index 解析设备）；当前 v0.7.0 版本发布了 97 个工具。此前的里程碑分别在 v0.5.2 中提供了 65 个认证工具，在 v0.5.6 源码里程碑中提供了 88 个工具，并在 v0.6.0 版本中提供了 96 个工具。v0.7.0 新增了 plan_user_journey、更新后的检索种子 v3（包含按集合划分的 SD3/GM 发音映射），以及专用的 UDP 实时控制通道。律动检索、证据、生成和比较均在离线状态下进行；只有受保护的应用路径会访问 Live。Python 编写的 FastMCP 服务通过 TCP 127.0.0.1:9888 与 MIDI Remote Script 通信，并通过 WebSockets 127.0.0.1:9889 与 Extension Host 桥接程序通信。

律动智能默认离线运行。其确定性生成器无需安装提供程序；可选的神经网络提供程序则受到固定许可列表、受限本地 IPC、资源限制和签名实验室门禁的隔离保护。提供程序发生故障时，始终会返回等效的确定性产物；不会向任何提供程序提供语料库路径、原始 MIDI、音符、SQL、凭据，也不会开放网络访问。请参阅提供程序实验室协议。 精选种子随 wheel 一同发布；可通过 ABLETON_GROOVE_SEED_BUNDLE 明确覆盖，派生产物则保存在 LocalAppData 中。律动检索、证据、比较和确定性生成均可移植，不依赖私有源库。生成请求可使用一个主律动和最多七个参考律动；不兼容的 PPQ、拍号或权利状态会被明确拒绝。在律动智能工具集中，唯一会修改 Live 的操作是受保护的 groove_apply；必须先针对明确指定的目标和空槽进行预览，才能提交一次更改。

---

⚡ 什么是 Model Context Protocol（MCP），Agent 如何使用它

Model Context Protocol（MCP） 是一项开放标准，用于大语言模型（LLM）与桌面应用之间的安全本地通信。

本地 IPC / stdio（非云服务）：
ableton-mcp-server 在你的主机操作系统上通过标准输入/输出（stdio）或 IPC 回环本地运行。AI Agent 会直接启动 ableton-mcp-server.exe 进程。无需外部云端点或 API 密钥，从而确保零网络延迟和最大程度的隐私保护。

AI Agent 如何与 Ableton Live 交互：

1. 发现工具（tools/list）：MCP 客户端（Antigravity、Cursor、Windsurf）启动服务后，会自动发现全部 97 个工具架构。
2. 执行工具（tools/call）：当大模型决定操控 Ableton Live 时，会发送 JSON-RPC 消息（例如 set_tempo(tempo=128.0) 或 create_clip(...)）。
3. 先写入后验证循环：服务会写入 Live 的本地套接字，并在返回结果前验证对象模型状态。
4. 自我纠错错误分类：如果发生错误，服务会返回结构化代码（CAPABILITY_UNAVAILABLE、AMBIGUOUS_MATCH、VERIFICATION_FAILED），让 Agent 能够分析并调整。

推荐的 AI Agent 系统提示词：

You have direct access to an active Ableton Live Set via ableton-mcp-server (97 tools) .
1. Always start by inspecting the project state using `get_session_overview()` or `get_track_list()`.
2. To modify track properties, resolve the target track index using `live_find_track(name_pattern)` first.
3. For parameter adjustments, query parameters via `get_device_list()` and `get_parameter_value()`, then apply changes using `set_parameter_value()`.
4. When executing multiple operations, bundle them using `run_batch(commands)` for one grouped undo step; a successful prefix persists if a later command fails.
5. Respect the error taxonomy: if you receive `AMBIGUOUS_MATCH` or `VERIFICATION_FAILED`, inspect track context and retry.

---

🛠️ 使用

许可证为 MIT。可复制、分叉并发布——请参阅 LICENSE。

Windows 安装（一次性）：

powershell -ExecutionPolicy Bypass -File .\scripts\setup_windows.ps1

预览确切的远程脚本复制计划，不创建 .venv-win、不安装依赖，也不向 Ableton 的 User Library 写入内容：

powershell -ExecutionPolicy Bypass -File .\scripts\setup_windows.ps1 -DryRun

如果环境已经存在，可使用等效的 CLI 预览：

.\.venv-win\Scripts\ableton-mcp.exe install-script --dry-run

然后重启 Live，在 Preferences -> Link, Tempo & MIDI -> Control Surfaces 下选择 AbletonMCPServer，并验证安装：

.\.venv-win\Scripts\ableton-mcp.exe doctor --json

验证安装

你可以使用内置 CLI 工具或直接比较 SHA-256 哈希值来验证安装完整性：

1. CLI 远程脚本状态

运行 install-status，将已安装的远程脚本文件与捆绑的源文件进行比较：

.\.venv-win\Scripts\ableton-mcp.exe install-status --json

正常且为最新版本的安装会返回 "status": "current"：

{
  "status": "current",
  "source": "C:\\path\\to\\ableton-mcp-server\\AbletonMCPServer_RemoteScript",
  "target": "C:\\Users\\<user>\\Documents\\Ableton\\User Library\\Remote Scripts\\AbletonMCPServer_RemoteScript",
  "missing_files": [],
  "mismatched_files": []
}

2. SHA-256 校验和审计

设置期间，setup_windows.ps1 会自动验证并打印远程脚本的 SHA-256 哈希值：

Remote Script verification:
  algorithm: SHA256
  hash: 3E3504D661FA2DCE7582F50C56F0C71EB79892F7A4520BD3F1B8571EEDBB14DE
  path: C:\Users\<user>\Documents\Ableton\User Library\Remote Scripts\AbletonMCPServer_RemoteScript\__init__.py

你可以随时手动计算并验证已安装的 __init__.py 的 SHA-256 校验和：

• Windows（PowerShell）：

  Get-FileHash "$HOME\Documents\Ableton\User Library\Remote Scripts\AbletonMCPServer_RemoteScript\__init__.py" -Algorithm SHA256
  

• macOS / Linux：

  shasum -a 256 "$HOME/Music/Ableton/User Library/Remote Scripts/AbletonMCPServer_RemoteScript/__init__.py"
  

Agent 配置（mcp.json）：

{
  "mcpServers": {
    "ableton": {
      "command": "C:\\path\\to\\ableton-mcp-server\\.venv-win\\Scripts\\ableton-mcp-server.exe",
      "args": []
    }
  }
}

如果你在 WSL2 中运行，请将 MCP 客户端指向 Windows 二进制文件，以便环回连接保留在主机网络命名空间中：

/path/to/ableton-mcp-server/.venv-win/Scripts/ableton-mcp-server.exe

MCP Bundle（.mcpb）

scripts/build_mcpb.py 会将服务打包为适用于 Windows 的 MCP Bundle。该 Bundle 包含 wheel 和锁定的启动器项目；首次启动时，主机的 uv 会从 PyPI 安装 Python 和依赖项。它只包含服务，因此远程脚本和扩展仍需按上述说明安装。

.\.venv-win\Scripts\python.exe scripts\build_mcpb.py build --out-dir dist\mcpb
.\.venv-win\Scripts\python.exe scripts\build_mcpb.py smoke dist\mcpb\ableton-mcp-server-<version>.mcpb

build 需要 uv、Node.js（npx 会运行固定版本的 @anthropic-ai/mcpb CLI）和网络连接。smoke 会解压 Bundle，通过 stdio 启动它，并检查 initialize、与目录对照的 tools/list，以及一个离线工具，无需 Ableton Live。

---

📦 功能说明（97 个 MCP 工具）

v0.6.0 在经过认证的 v0.5.2 基线（65 个工具）上扩展而来。v0.5.3 引入了颜色写入、片段目标诊断，以及 5 个先验证、再返回 CAPABILITY_UNAVAILABLE 的层级工具；v0.6.0 新增了离线音乐生成、Groove 检索和受保护的应用操作。请参阅离线音乐参考。

97 个 MCP 工具按操作领域分组：

• 传输与会话：get_session_info、set_tempo、start_playback、stop_playback、get_loop_settings、set_loop、set_loop_start、set_loop_length、set_current_song_time、get_song_length、get_session_overview、get_scenes、get_scene_state、fire_scene、fire_clip。
• 音轨与设备：get_track_list、live_find_track、live_find_device、live_find_clip、get_track_state、get_device_list、list_device_params、get_parameter_value、get_plugin_presets、set_plugin_preset、get_clip_summary、set_parameter_value、create_clip、get_clip_notes、add_notes_to_clip、delete_clip、clear_clip_notes、set_clip_properties、get_clip_info、set_track_property、set_track_color、set_clip_color、diagnose_clip_targets、create_midi_track、create_audio_track、rename_track、move_track、reorder_tracks、move_track_to_group、ungroup_track、merge_groups、get_routing、diff_snapshots_tool、take_snapshot、get_selected_context、get_composition_structure、diagnose_midi_clip、search_browser、load_device_to_track、get_warp_state、set_warp_state。
• 生命周期与自动化：lifecycle_status、save_set、quit_ableton、live_fade、create_clip_automation。
• 离线混音分析：analyze_audio、find_frequency_masking、analyze_mix、extract_single_cycle（LUFS-I、真峰值、动态范围、频谱冲突）。
• Groove 智能（默认离线）：groove_search、groove_evidence、groove_generate、groove_compare、groove_apply（流派／子流派／风格／段落分类体系、V2 投影、确定性多父级生成、后期鼓组映射，以及一次受保护的 Live 提交）。
• 检查与批量执行：run_batch、get_locators、create_cue_point、delete_cue_point、bulk_create_cue_points、get_control_surfaces、get_browser_categories、get_project_metadata、get_ableton_logs、get_bridge_status。

离线音乐生成

清单	工具	Live 边界
确定性音乐生成	music_generate_drum_groove、music_generate_bass、music_plan_production	默认离线；只有显式请求 apply 时才会访问 Live。

---

💡 灵感与先行项目

本项目汲取了开源先行项目中的设计见解：

• pnomolos/live-wire — TCP JSONL Remote Script 布局、类型化错误信封、逐刻度验证循环。
• hidingwill/AbletonBridge — run_batch 事务语义与属性验证。
• ideoforms/AbletonOSC — OSC 命令命名和 Extension Host 桥接约定。
• ideoforms/pylive — Python LOM 自省参考。
• Simon-Kansara/ableton-live-mcp-server — 工具边界设计（传输／设备使用 Remote Script，变调／浏览器加载使用 WebSocket Extension）。

完整说明见 docs/INSPIRATION.md。

---

⚠️ 已知问题

Live 的 Object Model 暴露了许多陷阱（路径 ID 漂移、撤销语义、WSL 回环、协议漂移、允许列表意外行为），AI Agent 可能会在毫无预警的情况下遇到。代码库中针对每个问题都有已知的规避方法；所有陷阱都记录在 docs/KNOWN_BUGS.md 中。在依赖音轨索引、run_batch 或连接到 Live 的 TCP 回环之前，请阅读该文件顶部的摘要。

---

📜 License

MIT — Copyright (c) 2026 Gabriel Worm (ntworm). See LICENSE.