> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vibrai.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Installation
> Install the Vibrai CLI and connect the MCP server.
## Prerequisites
| Requirement | Notes |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Ableton Live 12 | Standard, Suite, or Trial; must be open with a Live set loaded |
| `vibrai.amxd` device | The Max for Live device that runs the local bridge. The package installer copies it into your Ableton User Library for you — you just drag it onto a track |
The Vibrai device runs a small HTTP server on `http://localhost:3333`. Load it on any track in your Live set before running commands that talk to Live. Commands that only work with project files (`project info`, `project load`) work offline.
## Install Vibrai
Vibrai installs from a single signed **package installer** (`.pkg`) — no Homebrew. One installer sets up everything: the `vibrai` CLI, the MCP server and its Claude Desktop bundle, the Max for Live device, and the Python remote script.
1. **Quit Ableton Live** if it's open — the installer refuses to run while Live is running.
2. Download the **Vibrai package installer** (`.pkg`) from [vibrai.com](https://vibrai.com).
3. Double-click the `.pkg` and follow the prompts.
The installer:
* puts the `vibrai` CLI on your `PATH` at `/usr/local/bin/vibrai`,
* installs the MCP server and drops the Claude Desktop bundle at `/usr/local/lib/vibrai/Vibrai.mcpb` (no separate download),
* copies the `vibrai.amxd` device into your Ableton **User Library**,
* installs the Python remote script.
Next: [connect Claude Desktop](#connect-the-mcp-server) and [load the device into your Live set](#load-the-device-into-your-live-set).
**Windows is not supported in the 1.0 release — macOS only.** Vibrai 1.0 ships a macOS `.pkg` and a macOS-only Claude Desktop `.mcpb`; there is no Windows installer or Windows MCP binary in this release. Windows support is planned for a future 1.x release — follow [vibrai.com](https://vibrai.com) for updates.
## Connect the MCP server
The MCP server (`Vibrai.Mcp`) runs as a subprocess launched by your MCP client. The easiest path is the one-click `.mcpb` bundle for Claude Desktop.
**Claude Desktop (.mcpb bundle — recommended):**
On macOS the package installer already put the bundle on disk — there is **no separate download from vibrai.com**. It lives at `/usr/local/lib/vibrai/Vibrai.mcpb`.
1. In Finder, press **⌘⇧G** and enter `/usr/local/lib/vibrai/` to reveal the bundle.
2. Open Claude Desktop → **Settings** → **Extensions**.
3. Drag `Vibrai.mcpb` into the Extensions panel.
Claude Desktop installs the extension and restarts. The `vibrai.amxd` device is already in your Ableton User Library (the installer put it there) — just drag it onto a track (see below).
**Manual registration (Claude Code, Cursor, or any MCP client):**
Point the MCP client config at the MCP server binary the installer placed on disk:
```json theme={null}
{
"mcpServers": {
"vibrai": {
"command": "/usr/local/lib/vibrai/Vibrai.Mcp",
"env": {
"VIBRAI_LOG_FILE": "/tmp/vibrai-mcp.log",
"VIBRAI_LOG_LEVEL": "Warning"
}
}
}
}
```
The config file lives at `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS and `%APPDATA%\Claude\claude_desktop_config.json` on Windows. Restart the client after editing.
**Environment variables:**
| Variable | Default | Purpose |
| ------------------ | ----------------------- | -------------------------------------------------------------------- |
| `VIBRAI_URL` | `http://localhost:3333` | Override the bridge URL |
| `VIBRAI_LOG_LEVEL` | `Warning` | Verbosity: `Verbose` / `Debug` / `Information` / `Warning` / `Error` |
| `VIBRAI_LOG_FILE` | (stderr only) | Write a rolling log to a file |
## Load the device into your Live set
The package installer already copied `vibrai.amxd` into your Ableton **User Library**. To use it:
1. In Ableton Live, open your **User Library** in the browser.
2. Navigate to **Presets → Max Audio Effect → vibrai**.
3. Drag **vibrai.amxd** onto any track in your set.
The device runs a local server on `localhost:3333`. It does not process audio — it is purely the bridge between Vibrai and Live.
## Verify
**CLI:**
```bash theme={null}
vibrai --version
```
A healthy response shows both the CLI and bridge versions:
```
vibrai CLI: 1.0.0
vibrai bridge: 1.1.0 (vibrai-m4l)
```
If Live is not open yet, you will see `(unreachable at http://localhost:3333)` for the bridge — the CLI version still printed, so the install succeeded.
**MCP (from your AI client):**
Call `get_version`. A healthy response includes both the `bridge` and `python_bridge` fields:
```json theme={null}
{
"mcp": { "version": "1.0.0" },
"bridge": { "name": "vibrai-m4l", "version": "1.1.0" },
"python_bridge": { "name": "vibrai-python-bridge", "version": "0.1.0",
"live_version": "12.4.0", "schema_version": 1 }
}
```
If `bridge` reports `"status": "unreachable"`, the M4L device is not loaded or port 3333 is occupied by another process.
The `python_bridge` field covers automation read/write operations. If it is `null`, run `install_vibrai_remote_script` from your MCP client (or `vibrai install remote-script` from the CLI), restart Live, and enable Vibrai under **Preferences → Link/Tempo/MIDI → Control Surface**.
## Activate your license
Vibrai runs as a time-limited trial until you activate a license key. Activation binds your purchased key to this machine and is **CLI-only by design** — it changes your seat count, so it is never performed by an AI agent.
```bash CLI theme={null}
# Activate the key from your purchase confirmation email
vibrai license activate VIBRAI-XXXX-XXXX-XXXX
# Check trial or activation status at any time
vibrai license status
```
```text MCP (Claude Desktop) theme={null}
Activation is CLI-only. From an MCP client you can still read status:
What's my Vibrai license status?
Claude calls get_license_status (read-only). To clear an offline-grace
banner after reconnecting, ask it to recheck the license.
```
See the [License reference](/reference/license) for every command and the read-only MCP tools.
## Keep Vibrai up to date
Vibrai updates itself in place — the CLI binary, the Max for Live device, and the Python remote script. The MCP server binary is managed separately by Claude Desktop's extension manager, so `vibrai update` does not touch it.
```bash CLI theme={null}
# See whether a newer release is available — makes no changes
vibrai update --check
# Download, verify (SHA-256), and apply the latest release
vibrai update --yes
# Roll back to the previously installed binary
vibrai update --rollback
```
```text MCP (Claude Desktop) theme={null}
Ask Claude:
Check for a Vibrai update. (calls update — report only)
Update Vibrai to the latest version. (calls update with apply=true)
```
If Ableton Live is open during an update, the device and remote-script changes take effect after you restart Live.
## Uninstalling
Vibrai ships a first-class uninstaller on both surfaces. It previews what will be removed and asks you to confirm before deleting anything.
```bash CLI theme={null}
# Preview exactly what would be removed — deletes nothing
vibrai uninstall --dry-run
# Remove Vibrai (shows the plan, then prompts for confirmation)
vibrai uninstall
# Full clean removal: program files, app data, and the Ableton integration
vibrai uninstall --purge-data --remove-ableton
```
```text MCP (Claude Desktop) theme={null}
Ask Claude:
Uninstall Vibrai
Claude calls the uninstall tool. It runs preview-first: the first call
(confirm=false) returns a plan of what would be removed; confirm to actually
remove it (confirm=true). The MCP tool covers your app data, the Ableton
integration, and the Claude Desktop registration — but NOT the installed
program files. Those need root, which the MCP server can't obtain, so remove
them with `vibrai uninstall` from a terminal.
```
By default `vibrai uninstall` removes the **program files** (`/usr/local/bin/vibrai`, `/usr/local/lib/vibrai`) and deregisters the `vibrai` entry from Claude Desktop's config. Removing program files needs root, so the command re-runs itself under `sudo` and may prompt for your password. Your **license, session history, and the Ableton device** are left in place unless you opt in with the flags below.
| Flag | Effect |
| ----------------------------- | ----------------------------------------------------------------------------- |
| `--purge-data` | Also remove `~/Library/Application Support/Vibrai` (license, sessions, cache) |
| `--remove-ableton` | Also remove the Max for Live device and Python remote script |
| `--keep-claude-desktop-entry` | Leave the `vibrai` entry in Claude Desktop's config in place |
| `-y`, `--yes` | Skip the confirmation prompt (required for non-interactive use) |
| `--dry-run` | Print what would be removed and exit without removing anything |
If you can't run the CLI, remove the files by hand:
```bash theme={null}
# CLI, MCP server, and Claude Desktop bundle
sudo rm -rf /usr/local/lib/vibrai /usr/local/bin/vibrai
# Max for Live device
rm -rf ~/Music/Ableton/User\ Library/Presets/Audio\ Effects/Max\ Audio\ Effect/vibrai
# Python remote script
rm -rf ~/Music/Ableton/User\ Library/Remote\ Scripts/Vibrai
```
Then open `~/Library/Application Support/Claude/claude_desktop_config.json` and remove the `"vibrai"` entry under `mcpServers`, so Claude Desktop stops trying to launch a binary that's gone.
This removes the program files only. Your license and session history live in `~/Library/Application Support/Vibrai/` and are left in place — delete that directory too if you want a completely clean removal (you'll need to reactivate your license key if you reinstall later).
Not applicable — Windows isn't supported in the 1.0 release. See the [Install Vibrai](#install-vibrai) section above.