{
  "markdown": "# Ableton for AI\n\n<!-- mcp-name: io.github.peterkolbe/ableton-for-ai -->\n\n> [!IMPORTANT]\n> **For AI Agents:** Please read [AGENTS.md](./AGENTS.md) for detailed technical context and protocol specifications before working on this\n> project.\n\n**Ableton for AI** is the bridge between your DAW and AI models. It makes Ableton projects **hearable and visible** to AI models by\nimplementing the [Model Context Protocol (MCP)](https://modelcontextprotocol.io) and exporting detailed project data.\n\n## What can it do?\n\nConnect Ableton Live directly to MCP-capable AI clients (like Claude Desktop, Cursor, or Cline). The AI can inspect, analyze, and even modify your project in real-time.\n\n**Included Tools:**\n\n* `get_overview`: **SESSION DISCOVERY**. Provides tempo, locators, and a list of all tracks with their current mixer state (volume, panning, etc.).\n* `get_track`: **TRACK INSPECTION**. Comprehensive data for a single track: metadata, complete device chain, and all device parameters (with UI-readable strings).\n* `get_tracks`: **BULK TRACK INSPECTION**. Query full data for a range of tracks in a single parallelized call.\n* `analyze_stems`: **DEEP AUDIO ANALYSIS**. Triggers generation of audio summaries (.summary.json) and spectrograms (.spectrogram.webp) for all tracks.\n* `set_track_volume` / `set_track_panning`: **MIXER CONTROL**. Remotely adjust track faders and panning.\n* `set_device_parameter`: **REMOTE CONTROL**. Precisely adjust any parameter of any device in the project.\n\n**Included Resources:**\n\n* `ableton://stems/{track_name}/summary`: **AUDIO SUMMARY**. Compact analysis (JSON) containing LUFS, Peak, RMS, 10ms-frames, detected transients, and a `legend` field.\n* `ableton://stems/{track_name}/spectrogram`: **VISUAL ANALYSIS**. Log-frequency spectrogram image (WebP) for visual frequency inspection.\n* `ableton://stems/available/summaries`: Discovery resource for all tracks with available audio summaries.\n* `ableton://stems/available/spectrograms`: Discovery resource for all tracks with available spectrograms.\n\n---\n\n## How do I get started?\n\n### 1. Prepare your environment\n\n#### Install AbletonOSC\n\nThis project relies on **AbletonOSC** to communicate with Ableton Live.\n\n- Download and install [AbletonOSC](https://github.com/ideoforms/AbletonOSC).\n- Follow the instructions there to add it as a **Control Surface** in Ableton Live's Link/Tempo/MIDI settings.\n\n#### Install ableton-for-ai\n\n##### Option A: uv (Recommended)\n\n[uv](https://docs.astral.sh/uv/) lets you run the server directly without installing anything globally:\n\n```bash\nbrew install uv          # macOS (Homebrew)\n# or: curl -LsSf https://astral.sh/uv/install.sh | sh   (macOS/Linux)\n# or: powershell -c \"irm https://astral.sh/uv/install.ps1 | iex\"  (Windows)\n```\n\n##### Option B: pip\n\nRequires Python 3.11+ ([python.org](https://www.python.org/downloads/) or `brew install python`):\n\n```bash\npip install ableton-for-ai\n```\n\n### 2. Connect to your Chatbot (MCP Client)\n\nAdd the server to your MCP client configuration (e.g. Claude Desktop, Cursor, or Cline).\n\n##### Via uvx (if you installed uv)\n\n```json\n{\n  \"mcpServers\": {\n    \"ableton-for-ai\": {\n      \"command\": \"uvx\",\n      \"args\": [\"ableton-for-ai\"],\n      \"env\": {\n        \"STEMS_SOURCE_DIR\": \"/path/to/your/exported/stems\"\n      }\n    }\n  }\n}\n```\n\n##### Via pip (if you installed with pip)\n\n```json\n{\n  \"mcpServers\": {\n    \"ableton-for-ai\": {\n      \"command\": \"ableton-for-ai\",\n      \"env\": {\n        \"STEMS_SOURCE_DIR\": \"/path/to/your/exported/stems\"\n      }\n    }\n  }\n}\n```\n\n> [!NOTE]\n> **`STEMS_SOURCE_DIR`** must point to the folder where your exported audio stems are located. You need to export stems manually from Ableton Live (e.g. via \"Export Audio/Video\" with individual tracks selected), as there is currently no OSC API for triggering exports. The audio analysis tools (`analyze_stems`) will look for files in this directory.\n\n##### Where to put this config\n\n- **Claude Desktop (macOS):** `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Claude Desktop (Windows):** `%APPDATA%\\Claude\\claude_desktop_config.json`\n- **Cursor / Cline:** See their respective MCP documentation.\n\n**Restart your MCP client** after saving the config.\n\n### 3. Use it\n\nOnce connected, you can ask the AI about your project state. The AI will use the included tools and resources to fetch data directly from Ableton.\n\n**For audio analysis:** Export your stems from Ableton Live first (e.g. via *File → Export Audio/Video* with individual tracks selected) into your configured `STEMS_SOURCE_DIR`. This step must be done manually, as there is no API for triggering exports.\n\n**For complex tasks (e.g. mix feedback):** Give the chatbot context about your project. A good starting prompt includes genre, goal, and where your exported stems start (beat or locator). See [`agent-templates/mix-engineer.md`](./agent-templates/mix-engineer.md) for a ready-to-use prompt template.\n\n**Example prompts:**\n\n- \"What is the current tempo and how many tracks do I have?\"\n- \"Check the EQ settings on my Lead Synth track.\"\n- \"Show me an overview of the mixer state.\"\n- \"Analyze the stems and tell me if there are any frequency clashes.\"\n- \"Show me the spectrogram for the 'Kick' track.\"\n\n---\n\n## ⚙️ Configuration\n\nYou can customize the server behavior by setting environment variables or editing `config.py` (when running from source).\n\n| Variable                  | Default Value                   | Description                                             |\n|:--------------------------|:--------------------------------|:--------------------------------------------------------|\n| `LOG_LEVEL`               | `\"INFO\"`                        | Logging verbosity (`INFO` or `DEBUG`).                  |\n| `BASE_OUT_DIR`            | _auto_                          | Where analysis output is stored. Defaults to `{STEMS_SOURCE_DIR}/ableton-for-ai-out` if stems dir is set, else `~/.ableton-for-ai/out`. Override with an absolute path. |\n| `STEMS_SOURCE_DIR`        | `\"./stems\"`                     | Path where exported stems are located.                  |\n| `PREFERRED_AUDIO_FORMAT`  | `\"mp3\"`                         | Audio format to analyze (`mp3` or `wav`).               |\n| `SPECTROGRAM_QUALITY`     | `90`                            | Quality of WebP spectrograms (1-100).                   |\n| `RELEVANT_DEVICE_CLASSES` | `{\"Eq8\", \"Compressor\", ...}`    | List of Ableton device classes to include in extraction. |\n| `RELEVANT_DEVICE_NAMES`   | `{\"Pro-Q 4\"}`                   | List of specific plugin names to include.               |\n\n---\n\n## 🔌 Using Custom VSTs / Plugins\n\n\n### 1. Register the Plugin Name\n\nIn `config.py`, add the exact name of the plugin as it appears in Ableton to `RELEVANT_DEVICE_NAMES`.\n\n### 2. Auto-Populate Parameters (The `Options.txt` Trick)\n\nBy default, Ableton Live only exposes the parameters of a third-party plugin, if the overall **parameter number\nthreshold** (_PluginAutoPopulateThreshold) is **below 64** (\ndefault), [see here](https://help.ableton.com/hc/en-us/articles/6003224107292-Options-txt-file).\nYou can change this to 128 and hope that your favorite custom VSTs will be exposed. If they are still not exposed, because there are too\nmany (e.g. Fab Filter Pro Q 4),\nyou have to configure the parameters within ableton.\n\nForce Ableton to automatically expose parameters by adding `-_PluginAutoPopulateThreshold=128` to your `Options.txt`:\n\n- **Mac:** `~/Library/Preferences/Ableton/Live [Version]/Options.txt`\n- **Windows:** `%AppData%\\Ableton\\Live [Version]\\Preferences\\Options.txt`\n\n#### Mac Terminal Commands\n\nTo quickly set this up on a Mac, you can use these commands (replace `[Version]` with your actual Live version, e.g., `12.3.6`):\n\n```bash\n# 1. Navigate to the Preferences folder\ncd ~/Library/Preferences/Ableton/Live\\ 12.3.6/\n\n# 2. Create the Options.txt file (if it doesn't exist)\ntouch Options.txt\n\n# 3. Append the setting to the end of the file\necho \"-_PluginAutoPopulateThreshold=128\" >> Options.txt\n```\n\nOR open the file in a text editor and add the setting manually, e.g.\n\n```bash\nidea ~/Library/Preferences/Ableton/Live\\ 12.3.6/Options.txt\n```\n\n---\n\n## 📂 CLI: Analyze & Upload (No MCP required)\n\nThis method is ideal for LLMs that don't support MCP directly (like ChatGPT or the Claude Web Interface). It runs the same analysis pipeline locally and exports the results as files you can upload to any chatbot.\n\n### Available Commands\n\nFull audio analysis (summaries + spectrograms + full analysis JSONs):\n\n```bash\nableton-for-ai-cli analyze_stems\n```\n\nExtract Ableton project metadata only (tracks, devices, parameters):\n\n```bash\nableton-for-ai-cli extract_ableton_project_data\n```\n\nFull pipeline (audio analysis AND project data extraction):\n\n```bash\nableton-for-ai-cli analyze_stems_and_extract_ableton_project_data\n```\n\n> [!NOTE]\n> The OSC daemon starts automatically — no need to launch it manually.\n\n### Output\n\nThe results will be stored in the `./out` directory, organized into subfolders:\n\n* `./out/project/`: Contains the Ableton project JSON file.\n* `./out/summaries/`: Contains compressed audio analysis JSONs (optimized for AI).\n* `./out/spectrograms/`: Contains spectrogram WebP images for each stem.\n* `./out/analyses/`: Contains full high-resolution analysis JSONs.\n\n### Mixing with AI (Manual Upload)\n\n1. Export your stems from Ableton into your `STEMS_SOURCE_DIR`.\n2. Run `ableton-for-ai-cli analyze_stems` to generate analysis files.\n3. Drag and drop the files from your `out` folder into the chatbot (spectrograms `.webp` + analysis `.json`).\n4. Use a prompt like this:\n\n```markdown\nI have attached several audio analysis files (spectrograms and energy analysis).\nThe given files only reflect a part of the project timeline, see below in Part.\n\nGenre: Drum and Bass\nGoal: Improve the clarity of the lead synth and make sure it doesn't clash with the vocals.\nPart: The *.analysis.json and *.spectrogram.webp ONLY reflect the part starting at beat 113.\n\nPlease analyze the attached files and provide concrete mixing advice.\n```\n\n---\n\n## 🛠️ Development & Contributing\n\n### Local Setup (from source)\n\n```bash\ngit clone https://github.com/peterkolbe/ableton-for-ai.git\ncd ableton-for-ai\nuv sync\n```\n\nRun the MCP server from source:\n\n```json\n{\n  \"mcpServers\": {\n    \"ableton-for-ai\": {\n      \"command\": \"uv\",\n      \"args\": [\n        \"--directory\",\n        \"/absolute/path/to/ableton-for-ai\",\n        \"run\",\n        \"mcp_server_ableton.py\"\n      ],\n      \"env\": {\n        \"STEMS_SOURCE_DIR\": \"/path/to/your/stems\"\n      }\n    }\n  }\n}\n```\n\nRun CLI commands from source:\n\n```bash\nuv run ableton_client.py analyze_stems\nuv run ableton_client.py extract_ableton_project_data\nuv run ableton_client.py analyze_stems_and_extract_ableton_project_data\n```\n\n### MCP Inspector (Debugging)\n\nThe [MCP Inspector](https://github.com/modelcontextprotocol/inspector) is useful for testing and debugging the MCP server during development.\n\nStart it directly via terminal:\n\n```bash\nnpx -y @modelcontextprotocol/inspector uv '--directory /absolute/path/to/ableton-for-ai run mcp_server_ableton.py'\n```\n\nOr start the Inspector without presets and configure it manually:\n\n```bash\nnpx -y @modelcontextprotocol/inspector\n```\n\nThen enter the following in the Inspector UI:\n\n- **Command:** `uv`\n- **Arguments:** `--directory /absolute/path/to/ableton-for-ai run mcp_server_ableton.py`\n\n### Linting & Formatting\n\n```bash\nuv run ruff check .\nuv run ruff format .\n```\n\n### Publishing to MCP Registry\n\nTo publish a new version to the [official MCP Registry](https://registry.modelcontextprotocol.io/):\n\n```bash\nbrew install mcp-publisher\nmcp-publisher login github\nmcp-publisher publish\n```\n\nVerify the publication:\n\n```bash\ncurl \"https://registry.modelcontextprotocol.io/v0/servers?search=io.github.peterkolbe/ableton-for-ai\"\n```\n\nMake sure to update the `version` in both `server.json` and `pyproject.toml` before publishing.\n\n---\n\n## ⚠️ Known Limitations & Troubleshooting\n\n### Automation Tracking\n\n* **Not Supported:** Automation data is **not included** in the exports.\n* **Technical Reason:** The underlying `AbletonOSC` script does not reliably expose automation status or points in its current version.\n\n---\n\n## 📄 License\n\nThis project is licensed under the MIT License.\n\n\n---\n",
  "bytes": 12290,
  "sha": "f47d7438defc9313add0104892a2b0639812d71c1cfbab6f1474e555e21cbbc4",
  "repo_slug": "peterkolbe/ableton-for-ai",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_peterkolbe_ableton_for_ai_7f2c5d14/readme"
}