Total Reaper MCP

🚀 REAPER MCP 服务器

REAPER MCP 服务器是一个基于 MCP（模型上下文协议）的服务器，它通过简洁的 API 接口将 REAPER DAW 的功能开放出来。

🚀 快速开始

本项目在 macOS 上开发和测试，但由于 REAPER 提供了一致的跨平台支持，经过最小限度的适配后，它应该也能在 Windows 和 Linux 上运行。

✨ 主要特性

• 基于 MCP 协议，通过简洁 API 接口开放 REAPER DAW 功能。
• 采用 Lua - Python 混合架构，实现与 REAPER 的高效通信。
• 支持多种通信方式，包括文件和套接字（部分待完善）。
• 提供丰富的工具，涵盖核心 DAW 功能、音乐制作工具和高级特性。

📦 安装指南

快速安装（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. 设置桥接脚本

目前，仅 基于文件的桥接脚本 已完全实现并经过测试。基于套接字的桥接脚本存在，但缺少相应的服务器实现。

基于文件的桥接脚本（推荐）

此方法无需额外的依赖项，是最可靠的方式：

1. 将桥接脚本复制到 REAPER：

   cp lua/mcp_bridge_file_v2.lua ~/Library/Application\ Support/REAPER/Scripts/
   

2. 在 REAPER 中加载桥接脚本：
   • 打开 REAPER。
   • 转到“操作”→“显示操作列表”。
   • 点击“加载...”并选择 mcp_bridge_file_v2.lua。
   • 运行该操作（检查 REAPER 控制台以查看启动消息）。
3. 启动 MCP 服务器：

   python -m server.app
   

注意：服务器日志中会提到 mcp_bridge_file_v2.lua，请确保在 REAPER 中加载的是此版本。

基于套接字的桥接脚本（目前未实现）

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

3. 验证设置

1. 检查 REAPER 控制台显示：“MCP Bridge Started”。
2. 检查 Python 服务器显示：“Server ready. Waiting for connections...”。
3. 桥接脚本通过 ~/Library/Application Support/REAPER/Scripts/mcp_bridge_data/ 进行基于文件的通信。

💻 使用示例

测试

确保你已经完成以下操作：

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

然后运行测试：

pytest tests/ -v

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

对于集成测试：

pytest tests/test_integration.py -v

📚 详细文档

可用工具

REAPER MCP 服务器实现了 756 个工具，涵盖 40 多个类别，包括：

核心 DAW 功能

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

音乐制作工具

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

高级特性

• 音频分析与峰值检测
• 视频与视觉媒体支持
• 颜色管理
• 布局与屏幕设置管理
• 脚本扩展支持
• 等等

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

通信流程

基于文件的通信（推荐）

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

基于套接字的通信

1. MCP 客户端 → MCP 服务器（标准输入输出）
2. MCP 服务器 → REAPER Lua 桥接脚本（UDP 端口 9000）
3. Lua 桥接脚本执行 REAPER API 调用
4. Lua 桥接脚本 → MCP 服务器（UDP 端口 9001）
5. MCP 服务器 → MCP 客户端（标准输入输出）

卸载

./scripts/uninstall.sh

关于 REAPER

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

API 参考

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

• 轨道管理和路由
• 媒体项和片段
• MIDI 编辑
• 包络和自动化
• 效果器和插件
• 项目管理
• 传输控制
• 等等

有关当前实现的方法的详细信息，请参阅 IMPLEMENTATION_MASTER.md。

🔧 技术细节

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

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

通信流程如下：

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

📄 许可证

文档中未提及相关信息。

贡献说明

在添加新的 ReaScript 方法时，请遵循以下步骤：

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