# ahujasid/ableton-mcp architecture

> Architecture diagram of the GitHub repository ahujasid/ableton-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ahujasid/ableton-mcp
- Repository: https://github.com/ahujasid/ableton-mcp

## Overview

##### Project type and purpose
- This is an integration tool (open‑source plugin) that connects Ableton Live (via a MIDI Remote Script) to Claude AI using the Model Context Protocol (MCP).
- Purpose: allow Claude AI to send commands (create tracks, clips, control transport, load devices) to Ableton Live and receive session information back.

##### File structure
- Top‑level artifacts:
- AbletonMCP_Remote_Script/ – contains the Ableton Live MIDI Remote Script (`__init__.py`)
- MCP_Server/ – contains the Python MCP server (`server.py`)
- Dockerfile, pyproject.toml, smithery.yaml – build/deployment/configuration files
- No “frontend” or “backend” folders; instead two collaborating components: a client (the Remote Script) and the server (the Python MCP implementation).
- Configuration files indicate packaging for uv (uv.lock), Python dependency management (pyproject.toml), and Docker (Dockerfile).

##### Key insights from the README
- Two‑way JSON‑over‑TCP communication between Remote Script and MCP Server.
- The MCP Server is launched via uvx (the uv package manager) from Claude Desktop or Cursor.
- The Remote Script lives inside Ableton’s “MIDI Remote Scripts” directory and opens a socket to listen for commands from the MCP Server.
- The MCP Server implements MCP to translate Claude AI requests into JSON commands and send them to the Remote Script.

##### Main components
a. Ableton Live Application
- Loads the MIDI Remote Script plugin (AbletonMCP_Remote_Script).
- Exposes a socket endpoint for JSON commands (port X).
b. AbletonMCP Remote Script
- Connects inside Ableton Live, implements socket client/server for JSON messages.
- Translates JSON commands into Ableton Live API calls (track/clip manipulation, transport control).
c. MCP Server (Python)
- Listens on TCP for Remote Script connections.
- Implements Model Context Protocol to accept commands from Claude.
- Translates Claude MCP requests into JSON commands for the Remote Script, and returns JSON responses.
d. Claude Desktop / Cursor Client
- Launches the MCP Server via uvx (defined in claude_desktop_config.json).
- Sends MCP messages to the server when the user interacts with the AI.
e. External Dependencies
- Python 3.8+, uv (uv package manager), TCP/IP networking.
- Docker (optional) for containerized deployment.

##### Relationships and interactions
- Claude UI → MCP Server: sends MCP commands over standard IO (uvx) or socket.
- MCP Server ↔ Ableton Remote Script: bidirectional JSON over TCP socket.
- Ableton Remote Script → Ableton Live API: internal calls to manipulate tracks, clips, transport.
- MCP Server → Claude: returns status and results via MCP protocol.

##### Architectural patterns and design principles
- Plugin architecture: Ableton Remote Script plugs into Live.
- Client‑server pattern: Remote Script and MCP Server communicate over TCP.
- Protocol translation: MCP Server translates between MCP and JSON socket protocol.
- Separation of concerns: UI/CLI launch (uvx), protocol layer (MCP), domain logic (Ableton API calls).

##### Detail without over‑complication
- Port numbers if known.
- Where configuration files live (e.g., claude_desktop_config.json entry).
- Call out build/runtime steps (e.g., “uvx ableton-mcp” launch).
- Essential components and their interactions—more granular separation is better than lumping everything together.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% AI Client
    subgraph "AI/Client"
        Claude["Claude Client (Desktop/Cursor)"]:::client
    end

    %% Server/Protocol
    subgraph "Server/Protocol"
        MCP["MCP Server (Python/vx)"]:::server
    end

    %% Plugin
    subgraph "Plugin"
        Remote["AbletonMCP Remote Script"]:::plugin
    end

    %% Host Application
    subgraph "Host Application"
        Live["Ableton Live Application"]:::host
    end

    %% External Dependencies
    subgraph "External Dependencies"
        Ext["Python 3.8+, uv, TCP/IP, Docker"]:::dependency
    end

    %% Project Configuration Files
    subgraph "Project Files"
        DockerfileNode["Dockerfile"]:::config
        PyProj["pyproject.toml"]:::config
        UVLock["uv.lock"]:::config
        Smithery["smithery.yaml"]:::config
        Readme["README.md"]:::config
        License["LICENSE"]:::config
        PyVer[".python-version"]:::config
        GitIgnore[".gitignore"]:::config
    end

    %% Connections
    Claude -->|"MCP JSON over STDIO"| MCP
    MCP -->|"JSON over TCP (port X)"| Remote
    Remote -->|"Ableton API calls"| Live
    Live -->|"API events/responses"| Remote
    Remote -->|"JSON response"| MCP
    MCP -->|"MCP JSON response"| Claude
    Ext --> MCP
    Ext --> Remote

    %% Click Events
    click Remote "https://github.com/ahujasid/ableton-mcp/tree/main/AbletonMCP_Remote_Script/"
    click Remote "https://github.com/ahujasid/ableton-mcp/blob/main/AbletonMCP_Remote_Script/__init__.py"
    click MCP "https://github.com/ahujasid/ableton-mcp/tree/main/MCP_Server/"
    click MCP "https://github.com/ahujasid/ableton-mcp/blob/main/MCP_Server/server.py"
    click MCP "https://github.com/ahujasid/ableton-mcp/blob/main/MCP_Server/__init__.py"
    click DockerfileNode "https://github.com/ahujasid/ableton-mcp/tree/main/Dockerfile"
    click PyProj "https://github.com/ahujasid/ableton-mcp/blob/main/pyproject.toml"
    click UVLock "https://github.com/ahujasid/ableton-mcp/blob/main/uv.lock"
    click Smithery "https://github.com/ahujasid/ableton-mcp/blob/main/smithery.yaml"
    click Readme "https://github.com/ahujasid/ableton-mcp/blob/main/README.md"
    click License "https://github.com/ahujasid/ableton-mcp/tree/main/LICENSE"
    click PyVer "https://github.com/ahujasid/ableton-mcp/blob/main/.python-version"
    click GitIgnore "https://github.com/ahujasid/ableton-mcp/blob/main/.gitignore"

    %% Styles
    classDef client fill:#d4f7d4,stroke:#333,stroke-width:1px
    classDef server fill:#d4e2f7,stroke:#333,stroke-width:1px
    classDef plugin fill:#f7e2d4,stroke:#333,stroke-width:1px
    classDef host fill:#e0e0e0,stroke:#333,stroke-width:1px
    classDef dependency fill:#f0f0f0,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef config fill:#fff2cc,stroke:#333,stroke-width:1px,stroke-dasharray: 2 2
```
