# ableton-copilot-mcp

<div align="center">
  <img src="https://img.shields.io/badge/Ableton%20Live-12-9cf" alt="Ableton Live 版本">
  <img src="https://img.shields.io/badge/Node.js-20%2B-green" alt="Node.js 版本">
  <img src="https://img.shields.io/badge/TypeScript-5.8.2-blue" alt="TypeScript 版本">
  <img src="https://img.shields.io/badge/License-MIT-yellow" alt="许可证">
</div>

> 一个基于 [ableton-js](https://github.com/leolabs/ableton-js) 搭建的 MCP（Model Context Protocol）服务器，用于与 Ableton Live 的编排视图（Arrangement View）进行实时交互和控制，致力于辅助音乐制作人进行音乐制作。

## 🎯 注意

作为一名音乐制作人，我对使用Ableton来创作音乐有一些理解。其实在创作音乐的时候我们经常会需要解决一些比较繁琐的操作，比如音符属性人性化、合并音符、把一个轨道录制到另外一个音频轨道等，以前我们只能依赖于宿主DAW自己提供的一些功能来进行这些操作，但是现在大模型和MCP出现之后我们有了可以让AI帮我们进行自动化操作的可能性，尽管目前让AI直接生成音符、创作一首完整歌曲仍不太现实，它不能够生成出一个好听的歌曲，但让AI来帮我们进行辅助操作也是一种新的可能。

## 🎥 功能演示
这是一个对midi操作的简单演示视频

https://github.com/user-attachments/assets/0c83be0b-7dac-4519-b617-04bb28c9927e

## 🚀 功能特性

### 🎵 歌曲控制（Song）
- 获取歌曲基本信息（根音、音阶名称、速度、歌曲长度等）
- 获取所有音轨列表
- 创建 MIDI、音频和返送音轨
- 删除、复制音轨

### 🎹 音轨管理（Track）
- 获取音轨中的所有片段
- 在编排视图的轨道中创建空白 MIDI 片段
- 在轨道中根据给出的采样文件路径创建音频片段
- 设置音轨属性（静音、颜色、名称等）
- 复制 MIDI 片段到指定音轨

### 🎼 片段操作（Clip）
- 获取钢琴卷帘视图中的片段
- 获取、添加、删除和替换片段中的音符
- 设置片段属性（名称、颜色等）

### 🎧 音频操作（Audio）
- 支持对轨道内容进行录制

### 📝 状态管理（State）
- 操作历史记录追踪与详细日志
- 支持操作回滚（目前只支持音符操作）
- 浏览和恢复先前状态

### 🔌 设备管理（Device）
- 加载音频效果器、乐器和插件
- 修改设备参数
- 浏览库中可用设备

## 📝 待办事项
- 支持自动化包络的调整
- 支持更多快照类型（轨道属性、设备参数等）

## ⚠️ 注意
- 当AI直接对midi片段操作时可能会导致原有的音符丢失，无法使用ctrl + z 撤销，请谨慎操作，如有需要可以尝试让AI帮您回滚音符操作

## 📥 安装

### 必备条件 
- **Node.js** 环境：确保已安装 Node.js（建议 v20+），并可正常使用 `npx` 命令
  > 🔗 下载链接：[Node.js 官网](https://nodejs.org/)

### 安装步骤

#### 1. 安装 AbletonJS MIDI Remote Scripts

选择以下**三种方式之一**安装 MIDI Remote Scripts：

- **方式一：命令行一键安装（推荐）**  
  ```bash
  npx @xiaolaa2/ableton-copilot-mcp --install-scripts
  # 或使用简短形式
  npx @xiaolaa2/ableton-copilot-mcp -is
  ```

- **方式二：工具辅助安装**  
  1. 先启动 ableton-copilot-mcp（见下方使用方法）
  2. 让 AI 助手或手动调用 MCP 工具 `init_ableton_js` 完成自动安装
   
- **方式三：手动安装**  
  1. 在 Ableton 用户库中创建 "Remote Scripts" 文件夹：
     - Windows: `C:\Users\[用户名]\Documents\Ableton\User Library\Remote Scripts`
     - Mac: `/Users/[用户名]/Music/Ableton/User Library/Remote Scripts`
  2. 从 [ableton-js](https://github.com/leolabs/ableton-js) 项目下载 MIDI Remote Scripts
  3. 将下载的 `midi-script` 文件夹复制到上述位置
  4. 将文件夹重命名为 `AbletonJS`

## 🔧 使用方法

### 快速开始

1. **启动 Ableton Live**

2. **启用 AbletonJS 控制界面**
   - 打开 Ableton Live 设置：`Preferences` → `Link/MIDI`
   - 在 `MIDI` 标签页，找到 `Control Surface` 区域
   - 从下拉菜单中选择 `AbletonJS`

   <div align="center">
     <img src="./assets/images/setting.jpg" alt="Ableton Live MIDI Remote Scripts 配置" width="80%" style="border-radius: 8px; box-shadow: 0 4px 8px rgba(0,0,0,0.1);">
     <p><em>图1：Ableton Live 中启用 AbletonJS 控制界面</em></p>
   </div>

3. **连接 MCP 客户端**
   
   以下客户端均可作为 MCP 接入点：
   - [Cursor](https://www.cursor.com)
   - [Cherry Studio](https://github.com/CherryHQ/cherry-studio)
   - Claude Desktop
   - 其它MCP客户端


### 客户端配置

#### Cursor 配置示例

在 Cursor 设置中添加以下配置：

```json
"ableton-js-mcp": {
    "command": "npx",
    "args": [
        "-y",
        "@xiaolaa2/ableton-copilot-mcp"
    ]
}
```

如需使用最新版本：

```json
"ableton-js-mcp": {
    "command": "npx",
    "args": [
        "-y",
        "@xiaolaa2/ableton-copilot-mcp@latest"
    ]
}
```

#### 自定义数据存储路径（可选）

您可以通过环境变量 `BASE_PATH` 指定自定义数据存储位置：

```json
"ableton-js-mcp": {
    "command": "npx",
    "args": [
        "-y",
        "@xiaolaa2/ableton-copilot-mcp"
    ],
    "env": {
        "BASE_PATH": "D:\\ableton_copilot_mcp"
    }
}
```

> 💡 **提示**：存储路径用于保存日志文件、操作历史和状态快照等数据


## ✅ 兼容性测试

兼容性主要取决于 ableton-js 库的版本支持情况

| Ableton Live 版本 | 测试状态 |
| ----------------- | ------- |
| 12.1.10           | ✅ 已测试可用 |
| 11.x              | ⚠️ 待测试 |
| 10.x              | ⚠️ 待测试 |

## 🤝 贡献

欢迎提交问题和贡献代码，请通过 [GitHub Issues](https://github.com/xiaolaa2/ableton-copilot-mcp/issues) 提交问题或建议。

## 📄 许可证

本项目采用 [MIT 许可证](./LICENSE)。

## ⚠️ 免责声明
这是一个第三方集成项目，并非由 Ableton 官方开发。