Ableton Control Deck

Ableton Control Deck은 Ableton Live를 위한 로컬 MCP 브리지입니다. Claude Code, Claude Desktop, Codex 또는 MCP를 지원하는 모든 클라이언트가 Live 트랙, 클립, 트랜스포트, 디바이스 및 서드파티 플러그인 파라미터를 정확하게 읽기-확인(read-back-verified) 방식으로 제어할 수 있게 해주며, 로컬 상태 대시보드도 제공합니다.

모든 것은 사용자 머신에서 실행되며 루프백 주소에만 바인딩됩니다. 네트워크에 게시되거나 노출되지 않습니다.

Ableton 및 Ableton Live는 Ableton AG의 상표입니다. 이 프로젝트는 독립적인 커뮤니티 도구이며 Ableton과 제휴하거나 보증하지 않습니다.

작동 방식

• Live 원격 스크립트(remote-script/Control_Deck/)는 Ableton Live 내에서 Control Surface로 실행되며, 인증된 로컬 요청 프로토콜을 위해 UDP 포트 50711에서 수신 대기합니다. 이 스크립트가 노출하는 Live API는 명시적인 허용 목록(allowlist)이며, 일반 메서드 실행기가 아닙니다.

• MCP 서버(src/index.ts, dist/로 컴파일됨)는 Live 제어를 MCP 도구로 노출하며, 종속성이 없는 로컬 UDP 클라이언트(src/ableton-client.ts)를 통해 원격 스크립트와 통신합니다.

• npm run setup으로 생성되고 절대 커밋되지 않는 설치별 비밀 키(per-install secret)가 두 구성 요소 간의 모든 요청을 인증합니다.

• 읽기 전용 상태 서비스(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 악기를 직접 호스팅하며, Live의 자동 디바이스 패널을 훨씬 뛰어넘는 수천 개의 파라미터를 포함한 완전한 게시된 파라미터 카탈로그를 자체 루프백 채널(UDP 50714)을 통해 노출합니다.

• 선택적 네이티브 macOS 래퍼(macos/)는 로컬 주소에 고정된 WebKit 창에 대시보드를 표시하며, 외부 탐색은 차단됩니다.

• 선택적 로컬 SQLite 샘플 인덱스(src/sample-index.ts)는 외부 샘플 드라이브를 키워드, BPM, 키, 원샷/루프 종류별로 검색 가능하게 하며, 소스 오디오에는 절대 쓰지 않습니다.

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

설계 규칙

• 트랙 및 디바이스 변경에는 인덱스와 정확한 현재 이름이 모두 필요하며, 오래된 이름은 거부됩니다.

• 플러그인 로딩은 Live 자체 브라우저 인덱스를 통해 해결되며, 모호한 이름은 추측 대신 거부됩니다.

• 파괴적 작업(delete_track, 인덱스 재구축)에는 명시적인 확인 플래그가 필요합니다.

• 모든 변경 후에는 별도의 읽기-확인(read-back) 쿼리가 수행되며, 도구는 Live가 실제로 표시하는 값을 보고합니다.

• 완료된 요청 ID는 브리지에 의해 캐시되므로, 중복된 UDP 요청이 변경을 두 번 실행할 수 없습니다.

도구

• 읽기 확인이 포함된 상태, 트랜스포트, 템포, 박자, 곡 위치

• 트랙 목록 보기, 생성, 이름 변경 및 안전하게 삭제

• Session View MIDI 클립 생성 및 검증된 노트 내용 작성

• 씬, 클립, 선택 항목, 디바이스 및 Live가 노출하는 모든 파라미터 검사

• Live 브라우저를 통해 정확한 트랙에서 VST3/VST2/AU 플러그인 검색, 확인 및 로드

• 모호성 거부와 함께 정확한 브라우저 이름으로 네이티브 Live 디바이스(Drum Rack, Echo, Reverb 등) 로드

• 정규화된 값과 읽기 확인으로 서드파티 플러그인 파라미터 읽기 및 설정

• Live의 파라미터 한계를 넘어 OmniHost를 통해 완전히 인덱싱된 VST3 악기 제어

• 키워드, 폴더, BPM, 키, 지속 시간, 태그로 로컬 샘플 인덱스 검색

요구 사항

• macOS 13 Ventura 이상 (Apple Silicon 및 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 버튼을 사용하고, 압축을 풀고 폴더를 홈 폴더 같은 영구적인 위치로 이동하세요. Downloads 폴더에 두지 마세요 — 설치 프로그램이 서비스를 폴더 위치에 고정시키며, 이동을 요청할 것입니다.

3. 설치 프로그램 실행 — Install Ableton Control Deck.command를 마우스 오른쪽 버튼으로 클릭하고 열기를 선택하세요 (macOS는 다운로드된 파일의 경우 처음에 오른쪽 클릭이 필요합니다). 모든 것을 설치하고, 백그라운드 서비스를 시작하며, 완료되면 연결 가이드를 엽니다. 언제든지 다시 실행해도 안전합니다.

4. Live에서 Control Surface 활성화 — 설정 → Link, Tempo & MIDI → 빈 Control Surface 슬롯에서 Control Deck을 선택하세요 (설치 중에 Live가 켜져 있었다면 먼저 다시 시작하세요).

5. AI 에이전트 연결 — 열린 가이드(http://127.0.0.1:50713/connect)에는 모든 클라이언트에 대한 복사-붙여넣기 지침이 있습니다.

개발자 설정

npm run setup은 설치 프로그램이 사용하는 것과 동일한 엔진입니다 — 종속성 설치, TypeScript + OmniHost + 대시보드 빌드, 설치별 비밀 키, 원격 스크립트 설치, launchd 에이전트(작성 및 활성화). 멱등적(idempotent)이므로 변경 사항을 가져오거나 체크아웃을 이동한 후 다시 실행하세요.

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에서 설정 → Link, Tempo & MIDI를 열고 Control Deck이 Control Surface로 선택되어 있는지 확인하세요.

다른 에이전트 연결

대시보드의 연결 페이지(http://127.0.0.1:50713/connect)에는 Claude Code, Claude Desktop, Codex, Cursor, VS Code, Windsurf, Gemini CLI, Grok CLI, 완전 로컬 LLM 환경(LM Studio, Ollama via 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