Skip to content

docs: install from npm #182

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sasan1200 merged 1 commit into from
Oct 31, 2026
Merged

docs: install from npm #182

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 5 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
# ableton-mcp

[![npm](https://img.shields.io/npm/v/@cavi-ai/ableton-mcp)](https://www.npmjs.com/package/@cavi-ai/ableton-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![M8ven Score](https://m8ven.ai/badge/mcp/cavi-ai/ableton-mcp)](https://m8ven.ai/mcp/cavi-ai/ableton-mcp)

Expand All @@ -20,6 +21,8 @@ In Live's preferences, select **CaviMcpBridge** as a Control Surface. Then check
ableton-mcp doctor --json
```

To update, run the same `npm install -g` command, then `ableton-mcp install`, and restart Live so the bridge matches the server.

To run from a source checkout instead, clone the repository, run `npm ci`, and use `npm run cli --` in place of `ableton-mcp`.

## Quickstart
Expand Down Expand Up @@ -54,7 +57,7 @@ ableton-mcp call get_producer_workflow --args '{"query":"silent part","limit":3}

Search returns keyword candidates with their required arguments. Retrieve a chosen reference by its exact `workflow` name and named string `arguments`. Searching and reading guidance do not execute Live operations.

To try client wiring without Live, run `ABLETON_MCP_FIXTURE=1 npm start`.
To try client wiring without Live, run `ABLETON_MCP_FIXTURE=1 ableton-mcp serve`.

For a smaller initial tool catalog, set `ABLETON_MCP_TOOL_PROFILE=core` in the MCP server's environment. It advertises 63 common tools instead of the full catalog. Use the default `all` profile when an agent needs the complete MIDI, audio, rack, or snapshot toolset; restart the server after changing profiles. The CLI's direct `call` command remains independent of the discovery profile.

Expand Down Expand Up @@ -118,7 +121,7 @@ It publishes 328 tools, 9 concrete resources, 13 resource templates and 89 promp
| `ABLETON_MCP_SPLICE_ROOTS` | Existing macOS `~/Splice/Sounds` and `~/Library/Splice/Plug-in/samples` directories; otherwise `[]` | Override with a JSON array of absolute local Splice folders. Set `[]` to disable discovery. Local cache files are not proof of a download license; cloud search and sync are not supported. |
| `ABLETON_MCP_CONFIRMATION_DIR` | `~/.cavi/ableton-mcp/confirmations` | Confirmation tokens for CLI `call`. |
| `ABLETON_MCP_SNAPSHOT_DIR` | `~/.cavi/ableton-mcp/snapshots` | Saved track, device-chain, group-system, and MIDI-feel snapshots in separate subdirectories. |
| `ABLETON_MCP_FIXTURE` | unset | `1` makes `npm start` serve fixture data without Live. |
| `ABLETON_MCP_FIXTURE` | unset | `1` makes `ableton-mcp serve` serve fixture data without Live. |
| `ABLETON_MCP_TOOL_PROFILE` | `all` | `core`: 63 common tools; `producer`: 12 specialist/session tools; `directory`: named native tools without coordinators; `all`: every tool. Compact profiles retain full runtime result validation. |

## Security
Expand Down
16 changes: 8 additions & 8 deletions docs/ableton-mcp/source/pages/introduction/quickstart.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,14 +2,14 @@

## Register the server with an MCP client

Point the client at `cli.mjs serve` in your checkout. Use an absolute path:
After [installing](installation.md), point the client at `ableton-mcp serve`:

```json
{
"mcpServers": {
"ableton": {
"command": "node",
"args": ["/path/to/ableton-mcp/apps/ableton-mcp/src/cli.mjs", "serve"]
"command": "ableton-mcp",
"args": ["serve"]
}
}
}
Expand All @@ -22,9 +22,9 @@ The server speaks MCP over stdio. It publishes tools, resources and prompts.
The CLI calls the same service:

```bash
npm run cli -- status --json
npm run cli -- resource ableton://set/tracks --json
npm run cli -- call list_devices --args '{"trackId":"track-0"}' --json
ableton-mcp status --json
ableton-mcp resource ableton://set/tracks --json
ableton-mcp call list_devices --args '{"trackId":"track-0"}' --json
```

## Make a change
Expand All @@ -35,13 +35,13 @@ Every Live mutation is planned first, then executed.
2. Call the tool with `expectedStateVersion`. The result is a dry-run plan with a `confirmation`.

```bash
npm run cli -- call set_tempo --args '{"expectedStateVersion":12,"tempo":124}' --json
ableton-mcp call set_tempo --args '{"expectedStateVersion":12,"tempo":124}' --json
```

3. Execute the reviewed plan with its single-use token and plan hash:

```bash
npm run cli -- call set_tempo --args '{"expectedStateVersion":12,"tempo":124,"dryRun":false,"confirmationToken":"<token>","planHash":"<hash>"}' --json
ableton-mcp call set_tempo --args '{"expectedStateVersion":12,"tempo":124,"dryRun":false,"confirmationToken":"<token>","planHash":"<hash>"}' --json
```

If the Set changed after the plan was made, execution is refused. [Guarded mutations](../guides/guarded-mutations.md) covers the full contract.
Expand Down
Loading