使用说明

Ableton Live MCP服务器

🎵 专业的AI音乐制作助理

一个复杂的模型上下文协议（MCP）服务器，可以将任何AI助手转换为具有深厚音乐制作知识和实时DAW控制的专家Ableton Live合作者。

太长，读不下去了

这是什么？ 一个MCP服务器，让人工智能助手（如克劳德）控制Ableton Live并实时提供音乐制作指导。

免责声明： 这是一个在业余时间建立的正在进行的激情项目，得到了以下方面的大力支持克劳德代码。我的职业是解决方案云架构师，而不是音乐制作人——我的音乐知识充其量是有限的。我创建这个是为了创建一个有用的MCP工具并在此过程中学习。预计会有粗糙的边缘！

想看看有什么可能吗？ 看看展示 -使用此MCP服务器从头开始创建深房子轨道的完整演练。

🚀 特性

核心Ableton Live集成

实时OSC通信 -通过AbletonOSC远程脚本进行双向控制
完整的运输控制 -播放、停止、录制、撤消/重做、跳转、提示导航、会话录制、捕获MIDI
轨道运行 -音量、平移、静音、独奏、手臂、颜色、发送、创建、删除和复制曲目
场景操作 -启动、创建、删除、重命名和重新着色场景
剪辑管理 -启动、停止、创建、删除带有名称、长度、循环点控制和智能MIDI音符添加的剪辑
设备和插件控制 -参数自动化、设备信息、切换活动、按参数查询
回程和主轨道控制 -音量、平移、静音、返回曲目和主曲目的名称
歌曲属性 -摇摆、节拍器、超低音、循环控制、节奏

AI驱动的音乐智能

谐波分析 -智能按键检测和和弦进程建议
音乐理论引擎 -音阶滤波、音符量化和旋律协调
安排情报 -歌曲结构分析及改进建议
专业混音指导 -LUFS定位、频率分析和EQ建议
时间优化 -特定流派的BPM建议和能量曲线分析

企业级架构

整洁架构 明确分离关注点
坚实的原则 全程实施
依赖注入 使用依赖注入器
全面测试 代码覆盖率超过85%
类型安全 具有严格的mypy配置
结构化日志记录 格式丰富
错误处理 具有自定义异常层次结构

📋 先决条件

所需软件

Ableton现场 （任何最新版本）
AbletonOSC远程脚本 - 下载和安装指南
Python 3.11+ 使用pip

系统要求

记忆：最低4GB RAM，建议8GB
网络：OSC通信的本地网络接入
港口：11000-11001可用于OSC（可配置）

🔧 安装

选择您喜欢的安装方法：

选项1:Docker（推荐）

最简单的开始方式。无需安装Python。

# Pull and run (Linux)
docker run --network host ghcr.io/josefigueredo/ableton-mcp:latest

# Pull and run (macOS / Windows)
docker run -p 11000:11000/udp -p 11001:11001/udp \
  -e ABLETON_OSC_HOST=host.docker.internal \
  ghcr.io/josefigueredo/ableton-mcp:latest

或者使用Docker Compose：

# Download docker-compose.yml and run
curl -O https://raw.githubusercontent.com/josefigueredo/ableton-mcp/main/docker-compose.yml
docker-compose up

选项2:Python（用于开发）

最适合调试和为项目做出贡献。

# Clone the repository
git clone https://github.com/josefigueredo/ableton-mcp.git
cd ableton-mcp

# Create virtual environment
python -m venv venv

# Activate virtual environment
# On Windows:
venv\Scripts\activate
# On macOS/Linux:
source venv/bin/activate

# Install package in development mode
pip install -e .

# Install development dependencies (optional)
pip install -e ".[dev]"

配置AbletonOSC（两种方法都需要）

下载 AbletonOSC
复制 AbletonOSC 文件夹到Ableton MIDI远程脚本目录：
- 视窗: C:\ProgramData\Ableton\Live x.x\Resources\MIDI Remote Scripts\
- macOS: /Applications/Ableton Live x.x/Contents/App-Resources/MIDI Remote Scripts/
重新启动Ableton Live
首选 首选项>链接/节奏/MDI 并选择 AbletonOSC 在控制面插槽中

🎯 快速开始

启动服务器

Docker：

# Linux (uses host networking)
docker run --network host ghcr.io/josefigueredo/ableton-mcp:latest

# macOS / Windows
docker run -p 11000:11000/udp -p 11001:11001/udp \
  -e ABLETON_OSC_HOST=host.docker.internal \
  ghcr.io/josefigueredo/ableton-mcp:latest

python

# Start the MCP server
ableton-mcp

# Or run directly (useful for debugging)
python -m ableton_mcp.main

MCP集成

服务器提供以下核心工具：

连接管理

# Connect to Ableton Live
await mcp_client.call_tool("connect_ableton", {
    "host": "127.0.0.1",
    "send_port": 11000,
    "receive_port": 11001
})

传输控制

# Start playback
await mcp_client.call_tool("transport_control", {
    "action": "play"
})

# Get song information
song_info = await mcp_client.call_tool("get_song_info", {
    "include_tracks": True,
    "include_devices": True
})

智能音乐创作

# Add notes with music theory assistance
await mcp_client.call_tool("add_notes", {
    "track_id": 0,
    "clip_id": 0,
    "notes": [
        {"pitch": 60, "start": 0.0, "duration": 1.0},
        {"pitch": 64, "start": 1.0, "duration": 1.0}
    ],
    "quantize": True,
    "scale_filter": "major"
})

# Analyze harmony
harmony_analysis = await mcp_client.call_tool("analyze_harmony", {
    "notes": [60, 64, 67, 72],
    "suggest_progressions": True,
    "genre": "pop"
})

🏗️ 建筑

该项目实施 整洁架构 分层清晰：

┌─────────────────────────────────────────┐
│              Interfaces                 │  ← MCP Protocol
│         (MCP Server, CLI)               │
├─────────────────────────────────────────┤
│               Adapters                  │  ← Service Integration
│       (OSC, Service Adapters)           │
├─────────────────────────────────────────┤
│              Application                │  ← Use Cases
│           (Business Logic)              │
├─────────────────────────────────────────┤
│               Domain                    │  ← Core Business
│     (Entities, Services, Repos)         │
├─────────────────────────────────────────┤
│            Infrastructure               │  ← External Concerns
│    (OSC Client, Repositories)           │
└─────────────────────────────────────────┘

关键设计模式

仓储模式 用于数据访问抽象
用例模式 用于业务逻辑封装
适配器模式 用于外部服务集成
依赖注入 用于松耦合
命令模式 用于操作封装

🧪 测试

运行所有测试

pytest

跑步有保障

pytest --cov=ableton_mcp --cov-report=html

运行特定测试类别

# Unit tests only
pytest tests/unit/

# Integration tests
pytest tests/integration/

# Slow tests excluded
pytest -m "not slow"

类型检查

mypy ableton_mcp/

代码质量

# Format code
black ableton_mcp/ tests/

# Lint code
ruff ableton_mcp/ tests/

📚 api参考

可用工具

工具	说明	关键参数
`connect_ableton`	通过OSC连接到Ableton Live	`host`, `send_port`, `receive_port`
`transport_control`	播放、停止、录制、撤消、重做、跳转、提示导航	`action`, `value`
`get_song_info`	获取全面的歌曲信息	`include_tracks`, `include_devices`, `include_clips`
`track_operations`	音量、平移、静音、独奏、手臂、颜色、发送、复制	`action`, `track_id`, `value`, `color`, `send_id`
`scene_operations`	启动、创建、删除、重命名、重新着色场景	`action`, `scene_id`, `name`, `color`
`clip_operations`	获取/设置剪辑名称、长度、循环点、射击、停止	`action`, `track_id`, `clip_id`, `name`, `length`
`song_properties`	定位球、节拍器、超低音、绕圈、节奏	`action`, `value`
`return_track_operations`	回程轨道和主轨道控制	`action`, `return_id`, `value`, `name`
`device_operations`	获取设备信息、切换、获取/设置参数	`action`, `track_id`, `device_id`, `parameter_id`
`add_notes`	智能MIDI音符添加	`track_id`, `clip_id`, `notes`, `quantize`
`analyze_harmony`	音乐理论与和弦分析	`notes`, `suggest_progressions`, `genre`
`analyze_tempo`	节奏优化建议	`current_bpm`, `genre`, `energy_level`
`mix_analysis`	专业混音指导	`analyze_levels`, `target_lufs`, `platform`
`arrangement_suggestions`	歌曲结构优化	`song_length`, `genre`, `current_structure`

错误代码

代码	描述	分辨率
`CONNECTION_FAILED`	无法连接到Ableton Live	检查AbletonOSC安装和端口
`TRACK_NOT_FOUND`	轨道ID无效	验证轨道是否存在以及ID是否正确
`CLIP_NOT_FOUND`	剪辑引用无效	确保剪辑槽有内容
`VALIDATION_ERROR`	无效的参数值	检查参数范围和类型
`OSC_COMMUNICATION_ERROR`	OSC消息失败	验证Ableton Live是否正在运行并响应

🔧 配置

环境变量

# OSC Configuration
ABLETON_OSC_HOST=127.0.0.1
ABLETON_OSC_SEND_PORT=11000
ABLETON_OSC_RECEIVE_PORT=11001

# Logging Level
LOG_LEVEL=INFO

# Development Mode
DEBUG=False

自定义配置

from ableton_mcp.container import Container

# Configure container
container = Container()
container.config.osc.host.from_env("ABLETON_OSC_HOST", default="127.0.0.1")
container.config.osc.send_port.from_env("ABLETON_OSC_SEND_PORT", default=11000)

🔒 安全

网络安全注意事项

此应用程序使用 OSC（开放式声音控制） 通过UDP与Ableton Live通信。重要安全注意事项：

仅限本地使用：OSC通信未加密，专为本地DAW控制而设计
默认绑定：服务器绑定到 127.0.0.1 默认情况下为（localhost）
不要暴露在不受信任的网络中：切勿将端口11000-11001暴露于互联网或不受信任的网络
防火墙配置：确保防火墙仅将OSC端口限制为本地主机

# Example: Linux firewall rule to restrict OSC ports to localhost
sudo iptables -A INPUT -p udp --dport 11000:11001 -s 127.0.0.1 -j ACCEPT
sudo iptables -A INPUT -p udp --dport 11000:11001 -j DROP

安全扫描

该项目包括CI/CD中的自动安全扫描：

pip审计：每周依赖性漏洞扫描
CodeQL：安全问题的静态代码分析

有关完整的安全评估，请参阅文档/安全_评估.md.

🚀 生产部署

Docker（推荐）

官方Docker镜像可以在GitHub容器注册表上找到：

# Pull the latest image
docker pull ghcr.io/josefigueredo/ableton-mcp:latest

# Run with environment configuration
docker run -d \
  --name ableton-mcp \
  --restart unless-stopped \
  --network host \
  -e ABLETON_MCP_LOG_LEVEL=INFO \
  ghcr.io/josefigueredo/ableton-mcp:latest

使用Docker Compose：

# docker-compose.yml
services:
  ableton-mcp:
    image: ghcr.io/josefigueredo/ableton-mcp:latest
    network_mode: host # Linux
    # For macOS/Windows, use ports instead:
    # ports:
    #   - "11000:11000/udp"
    #   - "11001:11001/udp"
    environment:
      - ABLETON_OSC_HOST=127.0.0.1
      - ABLETON_MCP_LOG_LEVEL=INFO
    restart: unless-stopped

系统服务（Linux）

在没有Docker的情况下直接在主机上运行：

[Unit]
Description=Ableton Live MCP Server
After=network.target

[Service]
Type=simple
User=music
ExecStart=/usr/local/bin/ableton-mcp
Restart=on-failure
RestartSec=10
Environment=ABLETON_MCP_LOG_LEVEL=INFO

[Install]
WantedBy=multi-user.target

🤝 贡献

开发设置

# Install development dependencies
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

# Run tests before committing
pytest && mypy ableton_mcp/

代码规范

黑色用于代码格式化
拉夫对于linting
米皮用于类型检查
测试用于测试
约定式提交 用于提交消息

拉取请求流程

克隆该仓库
创建要素分支(git checkout -b feature/amazing-feature)
为您的更改编写测试
确保所有测试通过，覆盖率保持在85%以上
根据需要更新文档
使用常规提交格式提交
推送到您的分支机构并创建拉取请求

🐛 故障排除

常见问题

连接被拒绝

Error: [CONNECTION_FAILED] Failed to connect to Ableton Live

验证Ableton Live是否正在运行
检查AbletonOSC远程脚本是否已启用
确保端口11000-11001未被堵塞

导入错误

ModuleNotFoundError: No module named 'ableton_mcp'

在开发模式下安装： pip install -e .
验证虚拟环境是否已激活

OSC超时

Error: [OSC_COMMUNICATION_ERROR] OSC message timeout

检查Ableton Live是否响应
验证AbletonOSC脚本是否已正确加载
重新启动两个应用程序

📖 文档

额外资源

清洁建筑指南 -详细的架构说明
音乐理论整合 -音乐智能功能
OSC协议参考 -沟通详情
部署指南 -生产设置
贡献指南 -开发工作流程

API文档

生成API文档：

sphinx-build -b html docs/ docs/_build/

📄 许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

🙏 致谢

克劳德 由Anthropic-人工智能联合创始人和结对编程合作伙伴
GitHub规范工具包 -规范驱动的开发助手
Ableton现场 -行业领先的DAW平台
AbletonOSC -启用MCP集成的OSC远程脚本
模型上下文协议 -标准化AI助手集成
整洁架构 罗伯特C.马丁的原则
音乐理论资源 来自伯克利、Coursera和学术机构

🔮 路线图

版本1.1.0

[]实时音频分析集成
[]先进的排列智能
[]硬件控制器支持
[]云协作功能

版本1.2.0

[]机器学习模型集成
[]先进的混合自动化
[]跨DAW兼容层
[]性能优化套件

内置于❤️ 为音乐制作界

文档 • 贡献 • 问题 • 讨论