Ableton MCP Server

ableton-mcp-server

:globe_with_meridians: Live ランディングページ＆インタラクティブな 97 ツールカタログ · アーキテクチャ図 · エージェント向けプレイブック · ツール一覧

AI エージェント（Antigravity、Gemini、Codex）やオーディオ開発者が、実行中の Ableton Live 12 セットを検索、分析、操作、自動化できるオープンな Model Context Protocol（MCP） サーバーです。

現在、TCP、WebSockets、合成ルート、ローカル実行を通じて 97 個のツールを提供しています（デバイスの主な解決には 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、コレクションごとの SD3/GM アーティキュレーションマッピングを含む更新版の retrieval seed v3、専用の UDP リアルタイム制御チャネルが追加されました。グルーヴの検索、エビデンス、生成、比較はオフラインのままです。Live に到達するのは、ガードされた適用パスのみです。Python の FastMCP サーバーは、TCP 127.0.0.1:9888 上の MIDI Remote Script、および WebSockets 127.0.0.1:9889 上の Extension Host ブリッジと通信します。

Groove Intelligence はデフォルトでオフラインです。決定論的ジェネレーターの実行にプロバイダーのインストールは不要です。オプションのニューラルプロバイダーは、固定許可リスト、制限付きローカル IPC、リソース制限、署名済みラボゲートの背後に隔離されています。プロバイダーで障害が発生した場合は、常に同等の決定論的アーティファクトが返されます。また、プロバイダーがコーパスのパス、生の MIDI、ノート、SQL、認証情報を受け取ったり、ネットワークにアクセスしたりすることはありません。プロバイダーラボの契約を参照してください。厳選されたシードは wheel に含まれています。ABLETON_GROOVE_SEED_BUNDLE で明示的に上書きできますが、派生アーティファクトは LocalAppData に保存されます。グルーヴの検索、エビデンス、比較、決定論的生成は移植可能で、非公開のソースライブラリには依存しません。生成リクエストでは、プライマリグルーヴ 1 つと最大 7 つの参照を使用できます。互換性のない PPQ、拍子、または権利は明示的に拒否されます。Groove Intelligence の機能で Live を変更できるのは、ガードされた groove_apply のみです。適用前に明示的なターゲットと空のスロットを指定してプレビューし、その後 1 回のコミットを行う必要があります。

---

⚡ Model Context Protocol（MCP）とは？エージェントはどのように利用するのか

Model Context Protocol（MCP） は、LLM とデスクトップアプリケーション間の安全なローカル通信を実現するオープン標準です。

ローカル IPC／stdio（クラウドサービスではありません）：
ableton-mcp-server は、ホスト OS 上で標準入力／出力（stdio）または IPC ループバックを介してローカルに実行されます。AI エージェントは ableton-mcp-server.exe プロセスを直接起動します。外部のクラウドエンドポイントや API キーは不要で、ネットワーク遅延がゼロになり、プライバシーが最大限に保護されます。

AI エージェントと Ableton Live の連携方法：

1. ツールの検出（tools/list）：MCP クライアント（Antigravity、Cursor、Windsurf）がサーバーを起動すると、97 個すべてのツールスキーマを自動的に検出します。
2. ツールの実行（tools/call）：LLM が Ableton Live の操作を決定すると、JSON-RPC メッセージ（例：set_tempo(tempo=128.0) や create_clip(...)）を発行します。
3. 書き込み後の検証ループ：サーバーは Live のローカルソケットに書き込み、結果を返す前にオブジェクトモデルの状態を検証します。
4. 自己修正型のエラー分類：エラーが発生した場合、サーバーは構造化コード（CAPABILITY_UNAVAILABLE、AMBIGUOUS_MATCH、VERIFICATION_FAILED）を返し、エージェントが推論して対応できるようにします。

AI エージェント向けの推奨システムプロンプト：

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 に書き込んだりせずに、Remote Script の正確なコピー計画をプレビューします。

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 による Remote Script の状態確認

install-status を実行して、インストール済みの Remote Script ファイルと同梱のソースを比較します。

.\.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 が Remote Script の 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"
  

エージェントの設定（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 バンドル（.mcpb）

scripts/build_mcpb.py は、Windows 用の MCP バンドルとしてサーバーをパッケージ化します。このバンドルには wheel とロック済みのランチャープロジェクトが含まれており、初回起動時にホストの uv が PyPI から Python と依存関係をインストールします。含まれるのはサーバーのみのため、Remote Script と Extension は上記の説明に従って別途インストールしてください。

.\.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 はバンドルを展開し、stdio 経由で起動して、initialize、カタログとの tools/list の照合、および Ableton Live を使わないオフラインツール 1 つの動作を確認します。

---

📦 できること（97 個の MCP ツール）

v0.6.0 では、認定済みの v0.5.2 のベースラインである 65 個のツールを拡張しています。v0.5.3 ではカラーの書き込み、クリップターゲットの診断、および検証後に CAPABILITY_UNAVAILABLE を返す 5 つの階層ツールが導入されました。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 へのコミット 1 回）。
• インスペクションとバッチ実行：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 のオブジェクトモデルには、パス ID のずれ、取り消しのセマンティクス、WSL のループバック、プロトコルのずれ、許可リストに関する予期しない動作など、AI エージェントが予告なく遭遇する可能性のある落とし穴がいくつもあります。それぞれにはコードベース内に既知の回避策があり、すべての落とし穴がdocs/KNOWN_BUGS.mdに記載されています。トラックインデックス、run_batch、または Live への TCP ループバックを利用する前に、このファイル冒頭の概要を読んでください。

---

📜 License

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