remix-mcp: Instructions file for Claude Code

CLAUDE.md

Project Overview

remix-mcp is a Rust MCP (Model Context Protocol) server that enables AI assistants to control Ableton Live via OSC. It uses AbletonOSC as a bridge to Ableton's Live Object Model.

Architecture

Claude/Client <--stdio/JSON-RPC--> remix-mcp <--UDP/OSC--> AbletonOSC <--> Ableton Live

• MCP Server: Rust binary using rmcp crate, communicates via stdio
• OSC Client: Async UDP client using rosc crate, lazy-initialized via OscHandle
• AbletonOSC: Python Remote Script running inside Ableton (bundled as git submodule, our fork)

Why OSC?

Ableton's Python API (Live Object Model) runs inside Ableton's sandboxed Python interpreter. External processes cannot call it directly. AbletonOSC bridges this gap via UDP/OSC on port 11000.

Lazy OSC & Multi-Instance Support

AbletonServer::new() is sync and infallible — no sockets are opened until the first tool call. This ensures the MCP handshake always succeeds even when Ableton is not running.

The OSC layer uses a single UDP socket per instance (ephemeral port, no fixed port). Our AbletonOSC fork replies to the sender's actual address instead of hardcoded port 11001, so multiple remix-mcp instances (e.g. Claude Desktop + Claude Code) can control Ableton simultaneously without port contention.

Development Commands

# Build
cargo build
cargo build --release

# Test
cargo test                    # Unit tests (no Ableton required)
cargo nextest run             # Faster test runner (recommended)
cargo insta test              # Run with snapshot review

# Lint
cargo clippy
cargo fmt
cargo deny check              # License/vulnerability checking

# Run (requires Ableton Live with AbletonOSC enabled)
cargo run

# Install AbletonOSC Remote Script
cargo run -- install

# Check installation status
cargo run -- status

# Integration tests (requires Ableton Live with AbletonOSC)
cargo test --test integration -- --ignored --test-threads=1