REAPER MCP 服务器

一个通过干净的API接口暴露 REAPER DAW 功能的MCP（模型上下文协议）服务器。

平台支持

该项目在macOS上进行开发和测试，但在Windows和Linux上只需少量调整即可运行，因为REAPER提供了跨平台的一致性支持。

要求

• REAPER 6.83+（包括嵌入式Lua 5.4和完整的ReaScript API）
• Python 3.10+（用于MCP 1.1.2+）
• LuaSocket库（可选 - 仅在基于套接字的通信中需要）

架构

本项目采用混合的Lua-Python方法：

• Lua桥接：在REAPER内部运行，使用REAPER内置的Lua解释器处理API调用
• Python MCP服务器：提供MCP接口，通过基于文件的进程间通信与REAPER通信

通信流程：

1. MCP客户端发送请求 → Python服务器
2. Python服务器写入JSON文件 → 桥接目录
3. Lua桥接读取文件 → 执行REAPER API
4. Lua桥接写入响应 → 桥接目录
5. Python服务器读取响应 → 返回给MCP客户端

快速开始

对于AI/LLM集成（推荐）

# 使用默认配置文件（dsl-production: 53个工具）
# 包括自然语言DSL和基本生产工具
python -m server.app

# 或选择特定配置文件：
python -m server.app --profile dsl              # 最小自然语言工具集（15个工具）
python -m server.app --profile groq-essential   # 传统ReaScript工具集（146个工具）
python -m server.app --profile full             # 所有工具（600+个工具）

默认的dsl-production配置文件针对AI/LLM使用进行了优化，提供了自然语言命令以及基本的MIDI、FX和渲染工具。

快速安装（macOS）

./scripts/install.sh

这将：

• 将Lua桥接安装到REAPER的脚本文件夹
• 配置REAPER在启动时加载桥接
• 设置Python虚拟环境
• 创建启动脚本
• 可选地设置登录时自动启动

注意：快速安装脚本可能引用了过时的配置。为了最可靠的设置，请遵循下面的手动指令。

手动设置

1. 安装Python依赖项

# 创建并激活虚拟环境（需要Python 3.10+）
python3.10 -m venv .venv
source .venv/bin/activate  # 在Windows上：.venv\Scripts\activate

# 安装包
pip install -e .

2. 设置桥接

目前，只有基于文件的桥接完全实现并经过测试。基于套接字的桥接存在但缺乏相应的服务器实现。

桥接设置

MCP服务器通过基于文件的桥接与REAPER通信。这不需要额外的依赖项，并且是最可靠的方法。

1. 安装桥接：

   ./scripts/install_bridge.sh
   

2. 在REAPER中加载桥接：

   • 打开REAPER
   • 前往操作 → 显示操作列表
   • 点击“加载...”并从脚本文件夹中选择mcp_bridge_file_v2.lua
   • 运行该操作（检查REAPER控制台中的启动消息）

3. 启动MCP服务器：

   # 默认配置文件（dsl-production: 53个工具，带有自然语言界面）
   python -m server.app
   
   # 或使用特定配置文件
   python -m server.app --profile dsl      # 自然语言工具集（15个工具）
   python -m server.app --profile full     # 所有工具（600+个工具）
   

重要架构说明：

• 只有一个桥接脚本（lua/mcp_bridge.lua）支持所有配置文件
• 桥接包括传统的ReaScript函数（600+）和DSL函数
• 配置文件的选择发生在Python MCP服务器中，而不是在桥接中
• 桥接作为mcp_bridge_file_v2.lua安装以保持向后兼容性

基于套接字的桥接（当前未实现）

虽然Lua脚本lua/mcp_bridge.lua存在用于基于套接字的通信，但没有对应的Python服务器实现。基于套接字的桥接需要LuaSocket，并且需要一个监听UDP端口9000的服务器。

3. 验证设置

1. 检查REAPER控制台显示：“REAPER MCP Bridge（基于文件，全API）已启动”
2. 检查Python服务器显示：“服务器已就绪。等待连接...”
3. 服务器将显示哪个配置文件处于活动状态以及注册了多少工具
4. 桥接通过~/Library/Application Support/REAPER/Scripts/mcp_bridge_data/进行基于文件的通信

测试

确保你已经：

1. 运行REAPER并加载mcp_bridge_file_v2.lua
2. 运行MCP服务器（python -m server.app）

然后运行测试：

pytest tests/ -v

要测试特定配置文件：

# 测试DSL工具
MCP_TEST_PROFILE=dsl pytest tests/test_dsl_minimal.py -v

# 使用不同的配置文件测试
MCP_TEST_PROFILE=mixing pytest tests/test_integration.py -v

注意：由于时间问题或轻微的输出格式差异，某些测试可能会失败。核心功能已被验证为正确工作。

对于集成测试：

pytest tests/test_integration.py -v

自然语言测试

REAPER MCP服务器包括全面的自然语言处理（NLP）测试，以确保系统能够正确地将用户意图映射到适当的工具。这些测试对于AI/LLM集成尤为重要。

基本NLP测试

# 从reaper-chat目录
cd reaper-chat
node test-nlp-mcp-mapping.js

这将运行测试，验证自然语言输入是否正确映射到MCP工具。

带有对话跟踪的增强NLP测试

为了进行全面测试，具有质量评估和改进跟踪：

# 确保你设置了OpenAI API密钥
export OPENAI_API_KEY=your-api-key-here

# 运行带有对话跟踪的增强测试
node test-nlp-with-tracking.js

这个高级测试套件：

• 通过MCP执行实际的REAPER命令
• 在多个维度上评估响应质量
• 跟踪所有对话以进行模式分析
• 生成可操作的改进报告

详见 reaper-chat/RUN-TRACKED-TESTS.md：

• 如何运行增强测试套件
• 如何理解质量指标
• 如何使用对话跟踪进行持续改进
• 如何实施建议的改进

对话跟踪系统会在reaper-chat/conversation-tracking/中创建详细的报告，帮助识别：

• 常见失败模式
• 需要改进的具体查询
• 测试会话之间的进度跟踪

工具配置文件

REAPER MCP服务器支持工具配置文件，根据你的需求或LLM限制来限制暴露的工具数量。许多LLM有工具数量限制（例如，Groq：128，OpenAI：128），配置文件可以帮助你在这些限制内专注于你需要的工具。

可用配置文件

配置文件	工具数量	描述	使用场景
dsl-production	~53	DSL + 基本工具	默认 - 自然语言 + 核心生产
dsl	15	自然语言DSL工具	最小化的AI友好界面
groq-essential	~146	核心REAPER功能	传统的ReaScript界面，Groq兼容
groq-extended	~200+	扩展功能	更多工具，可能超过Groq的限制
minimal	~100	最基础工具	测试和轻量级操作
midi-production	~150	MIDI聚焦工具	MIDI创作和编辑工作流
mixing	~120	混音和母带工具	音频混音、效果和路由
full	600+	所有可用工具	完整访问（可能会使LLM超载）

使用配置文件

# 列出所有可用配置文件
python -m server.app --list-profiles

# 使用默认配置文件（dsl-production）
python -m server.app

# 使用特定配置文件
python -m server.app --profile dsl           # 最小自然语言（15个工具）
python --m server.app --profile groq-essential # 传统的ReaScript界面
python -m server.app --profile mixing         # 混音聚焦工具
python -m server.app --profile full           # 所有600+个工具

# 使用中继脚本
python run_with_relay.py                      # 使用默认（dsl-production）
python run_with_relay.py --profile dsl        # 最小DSL配置文件

DSL（自然语言）特性

DSL工具（包含在默认的dsl-production配置文件中）提供了一个易于自然语言理解的接口，可以理解灵活的输入：

• 轨道引用："bass"，"drums"，"track 3"，"last track"
• 音量格式："−6dB"，"+3"，"50%"
• 时间引用："8 bars"，"cursor"，"selection"
• 声像格式："L50"，"R30"，"center"

DSL使用示例：

# 替代复杂的ReaScript调用：
await dsl_track_create(name="Bass", role="bass")
await dsl_track_volume(track="bass", volume="-6dB")
await dsl_loop_create(track="bass", time="8 bars")

创建自定义配置文件

在server/tool_profiles.py中添加自己的配置文件：

"my-workflow": {
    "name": "我的自定义工作流",
    "description": "满足我特定需求的工具",
    "categories": [
        "DSL",          # 自然语言工具
        "Tracks",       # 轨道管理
        "MIDI",         # MIDI操作
        "FX",           # 效果
    ]
}

可用工具

REAPER MCP服务器实现了600+个工具，跨越40+类别。可用的工具数量取决于你选择的配置文件（参见上面的工具配置文件部分）。

核心DAW功能

• 轨道管理和控制
• 媒体项和片段
• MIDI操作
• 效果/FX管理
• 自动化和包络
• 项目管理
• 运输和播放

音乐制作工具

• 循环和时间选择管理 - 循环点、时间选择、网格量化
• 弹出和渲染操作 - 轨道弹出、冻结、导出stem
• 节奏和量化 - 人性化、摇摆、复节奏、节拍检测
• 总线路由和混音 - 子混音、并行压缩、侧链路由

高级功能

• 音频分析和峰值检测
• 视频和视觉媒体支持
• 色彩管理
• 布局和屏幕集管理
• 脚本扩展支持
• 以及其他更多

有关所有已实现方法的完整列表，请参阅 IMPLEMENTATION_MASTER.md。

通信流程

基于文件（推荐）：

1. MCP客户端 → MCP服务器（标准I/O）
2. MCP服务器 → REAPER Lua桥接（通过JSON文件）
3. Lua桥接执行REAPER API调用
4. Lua桥接 → MCP服务器（通过JSON文件）
5. MCP服务器 → MCP客户端（标准I/O）

基于套接字：

1. MCP客户端 → MCP服务器（标准I/O）
2. MCP服务器 → REAPER Lua桥接（UDP端口9000）
3. Lua桥接执行REAPER API调用
4. Lua桥接 → MCP服务器（UDP端口9001）
5. MCP服务器 → MCP客户端（标准I/O）

卸载

./scripts/uninstall.sh

关于REAPER

REAPER 是一款适用于计算机的完整数字音频制作应用程序，提供全面的多轨音频和MIDI录制、编辑、处理、混音和母带工具集。REAPER支持Windows、macOS和Linux，提供跨平台的一致性功能。

API参考

此项目实现了REAPER ReaScript API的一个子集。ReaScript API提供了对REAPER功能的全面控制，包括：

• 轨道管理和路由
• 媒体项和片段
• MIDI编辑
• 包络和自动化
• 效果和插件
• 项目管理
• 运输控制
• 以及其他更多

详情请参阅 IMPLEMENTATION_MASTER.md，了解当前已实现的方法。

贡献

当添加新的ReaScript方法时：

1. 检查IMPLEMENTATION_MASTER.md中的实现检查表
2. 遵循代码库中的现有模式
3. 为所有新方法编写测试
4. 更新实现主列表