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. 更新實現主列表。