使用说明

REAPER MCP服务器

一个MCP（模型上下文协议）服务器，它公开收割者黎明通过一个干净的API接口实现功能。

平台支持

该项目是在 macOS 但应该在Windows和Linux上工作，只需进行最小的调整，因为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接口，通过基于文件的IPC与REAPER通信

通信流程：

MCP客户端发送请求→ Python服务器
Python服务器写入JSON文件→ 网桥目录
Lua桥读取文件→ 执行REAPER API
Lua bridge写回应→ 网桥目录
Python服务器读取响应→ 返回MCP客户端

快速开始

用于AI/LLM集成（推荐）

# Start with default profile (dsl-production: 53 tools)
# Includes natural language DSL + essential production tools
python -m server.app

# Or choose a specific profile:
python -m server.app --profile dsl              # Minimal natural language only (15 tools)
python -m server.app --profile groq-essential   # Traditional ReaScript tools (146 tools)
python -m server.app --profile full             # All tools (600+ tools)

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

快速安装（macOS）

./scripts/install.sh

这将：

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

注：快速安装脚本仅适用于macOS。Windows用户必须遵循下面的手动设置。

手动设置

1.安装Python依赖项

macOS/Linux：

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Windows（推荐使用紫外线):

uv venv --python 3.11
source .venv/Scripts/activate   # Git Bash
# or: .venv\Scripts\activate.bat  (CMD) / .venv\Scripts\Activate.ps1 (PowerShell)
uv pip install -e .

窗户（标准百叶窗）：

python -m venv .venv
.venv\Scripts\activate.bat      # CMD
# or: .venv\Scripts\Activate.ps1  (PowerShell)
pip install -e .

2.架设桥梁

目前，只有 基于文件的网桥 已全面实施和测试。基于套接字的网桥存在，但缺少相应的服务器实现。

桥梁设置

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

macOS/Linux：

安装桥架：
```
./scripts/install_bridge.sh
```

窗户：

安装脚本仅适用于macOS。手动复制网桥：

# Git Bash
cp lua/mcp_bridge.lua "$APPDATA/REAPER/Scripts/"

或者在PowerShell中：

Copy-Item lua\mcp_bridge.lua "$env:APPDATA\REAPER\Scripts\"

桥被复制为 mcp_bridge.lua.REAPER的Scripts文件夹通常为： C:\Users\<you>\AppData\Roaming\REAPER\Scripts\

在后部装载桥梁（所有平台）：

打开后盖
首选 行动→ 显示操作列表
点击 新的诉讼 按钮
选择 加载ReaScript。.. 从出现的选项中
导航到Scripts文件夹并选择 mcp_bridge.lua （Windows）或 mcp_bridge_file_v2.lua （macOS）
- Windows脚本文件夹： C:\Users\<you>\AppData\Roaming\REAPER\Scripts\
- macOS脚本文件夹： ~/Library/Application Support/REAPER/Scripts/
脚本出现在操作列表中——选择它并单击跑
检查后部控制台(View → 显示REAPER控制台)用于： "REAPER MCP Bridge (File-based, Full API) started"

启动MCP服务器：

# Default profile (dsl-production: 53 tools with natural language interface)
python -m server.app

# Or with a specific profile
python -m server.app --profile dsl      # Natural language tools only (15 tools)
python -m server.app --profile full     # All tools (600+ tools)

重要架构说明：

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

基于套接字的网桥（目前尚未实现）

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

3.连接到克劳德代码（或其他MCP客户端）

克劳德代码(claude mcp add):

# macOS / Linux
claude mcp add reaper-mcp -- /path/to/.venv/bin/python -m server.app

# Windows — must set REAPER_MCP_BRIDGE_DIR explicitly (default path is macOS-only)
claude mcp add reaper-mcp \
  -e REAPER_MCP_BRIDGE_DIR="C:/Users/<you>/AppData/Roaming/REAPER/Scripts/mcp_bridge_data" \
  -- C:/path/to/.venv/Scripts/python.exe -m server.app

如果您已经添加了不带env变量的服务器，请编辑 ~/.claude.json 并将其添加到 "env" 字段：

"reaper-mcp": {
  "type": "stdio",
  "command": "C:/Users/<you>/github/total-reaper-mcp/.venv/Scripts/python.exe",
  "args": ["-m", "server.app"],
  "env": {
    "REAPER_MCP_BRIDGE_DIR": "C:/Users/<you>/AppData/Roaming/REAPER/Scripts/mcp_bridge_data"
  }
}

4.验证设置

检查REAPER控制台显示：“REAPER MCP桥接（基于文件，完整API）已启动”
检查Python服务器显示：“服务器就绪。正在等待连接…”
服务器将显示哪个配置文件处于活动状态以及注册了多少工具
网桥通过以下方式使用基于文件的通信：
- macOS： ~/Library/Application Support/REAPER/Scripts/mcp_bridge_data/
- 窗户： %APPDATA%\REAPER\Scripts\mcp_bridge_data\

Windows遇到问题： Python服务器默认为macOS桥接路径。无设置 REAPER_MCP_BRIDGE_DIR，即使REAPER和Lua桥正在运行，所有工具调用也会超时。

测试

确保你有：

REAPER跑步 mcp_bridge.lua 已加载（macOS： mcp_bridge_file_v2.lua)
MCP服务器正在运行(python -m server.app)

然后运行测试：

pytest tests/ -v

要测试特定配置文件：

# Test DSL tools
MCP_TEST_PROFILE=dsl pytest tests/test_dsl_minimal.py -v

# Test with a different profile
MCP_TEST_PROFILE=mixing pytest tests/test_integration.py -v

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

对于具体的集成测试：

pytest tests/test_integration.py -v

自然语言测试

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

NLP基础测试

# From the reaper-chat directory
cd reaper-chat
node test-nlp-mcp-mapping.js

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

使用会话跟踪增强NLP测试

对于具有质量评估和改进跟踪的综合测试：

# Ensure you have an OpenAI API key set
export OPENAI_API_KEY=your-api-key-here

# Run enhanced tests with conversation tracking
node test-nlp-with-tracking.js

这个高级测试套件：

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

看收割者聊天/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功能	传统工具，兼容Groq
`groq-extended`	~200+	扩展功能	更多工具，可能超过Groq的限制
`minimal`	~100	最低限度的工具	测试和轻量级操作
`midi-production`	~150	以MIDI为中心的工具	MIDI作曲和编辑工作流程
`mixing`	~120	混音和母带制作工具	音频混音、效果和布线
`full`	600+	所有可用工具	完全访问（可能会淹没LLM）

使用配置文件

# List all available profiles
python -m server.app --list-profiles

# Start with default profile (dsl-production)
python -m server.app

# Start with a specific profile
python -m server.app --profile dsl           # Minimal natural language (15 tools)
python -m server.app --profile groq-essential # Traditional ReaScript interface
python -m server.app --profile mixing         # Mixing-focused tools
python -m server.app --profile full           # All 600+ tools

# Using with the relay script
python run_with_relay.py                      # Uses default (dsl-production)
python run_with_relay.py --profile dsl        # Minimal DSL profile

DSL（自然语言）功能

DSL工具（包含在默认设置中 dsl-production profile）提供了一个自然语言友好的界面，可以理解灵活的输入：

跟踪引用：“贝斯”、“鼓”、“第三首曲目”、“最后一首曲目”
卷格式：“-6dB”、“+3”、“50%”
时间参考：“8栏”、“光标”、“选择”
平移格式：“L50”、“R30”、“中心”

DSL使用示例：

# Instead of complex ReaScript calls:
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": "My Custom Workflow",
    "description": "Tools for my specific needs",
    "categories": [
        "DSL",          # Natural language tools
        "Tracks",       # Track management
        "MIDI",         # MIDI operations
        "FX",           # Effects
    ]
}

可用工具

REAPER MCP服务器实现 600+工具 40多个类别。可用工具的数量取决于您选择的配置文件（请参阅上面的“工具配置文件”部分）。

DAW核心功能

轨道管理和控制
媒体项目和拍摄
MIDI操作
效果/外汇管理
自动化和信封
项目管理
传输与回放

音乐制作工具

循环和时间选择管理 -循环点、时间选择、网格量化
反弹和渲染操作 -跟踪反弹、冻结、阀杆出口
沟槽和量化 -人性化、摇摆、多节奏、节奏检测
巴士路线和混合 -子像素、并行压缩、侧链路由

高级功能

音频分析和峰值检测
视频和视觉媒体支持
颜色管理
布局和屏幕集管理
脚本扩展支持
还有更多

有关所有已实现方法的完整列表，请参阅实施_已完成.md.

通信流

基于文件（推荐）：

MCP客户端→ MCP服务器（stdio）
MCP服务器→ REAPER Lua Bridge（通过JSON文件）
Lua Bridge执行REAPER API调用
Lua桥接→ MCP服务器（通过JSON文件）
MCP服务器→ MCP客户端（stdio）

基于套接字：

MCP客户端→ MCP服务器（stdio）
MCP服务器→ REAPER Lua网桥（UDP端口9000）
Lua Bridge执行REAPER API调用
Lua桥接→ MCP服务器（UDP端口9001）
MCP服务器→ MCP客户端（stdio）

卸载

./scripts/uninstall.sh

关于REAPER

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

API 参考

此项目实现了 REAPER重新编写API脚本.ReaScript API提供了对REAPER功能的全面控制，包括：

轨道管理和路线
媒体项目和拍摄
MIDI编辑
信封和自动化
效果和插件
项目管理
传输控制
还有更多

看实施_已完成.md 有关当前实现的方法的详细信息。

贡献

添加新的ReaScript方法时：

检查implementation_MASTER.md中的实施检查表
遵循代码库中的现有模式
包括所有新方法的测试
更新实施主列表