Reaper Reapy Mcp

Reaper 与 MCP 或 AI 集成

一个使用 MCP（Model context protocol）控制 REAPER 数字音频工作站（DAW）的 Python 应用。

功能

• 音轨管理：创建、重命名和设置音轨颜色
• FX 管理：添加、移除和控制效果参数
• 项目控制：设置速度、管理区域和标记
• 主音轨控制：音量、声像、静音和独奏操作
• MIDI 操作：使用音乐位置创建条目、添加/获取音符、清除条目
• 音频条目操作：插入、复制和修改，并增强位置支持
• 双位置格式：同时支持时间（秒）和小节:拍记法
• 可靠复制：使用 REAPER 内置命令准确复制条目
• MCP 集成：用于控制 AI 助手的 Model Context Protocol 服务

状态

• 已在 Linux 上检查：是
• MCP HTTP 模式：支持参数

要求

• Python 3.7+
• REAPER DAW
• python-reapy Python 模块
• 用于 MCP 服务的 mcp[cli] 软件包
• 互联网连接（用于下载示例音频文件）

安装

1. 如果尚未安装，请安装 REAPER
2. 通过 REAPER 脚本启用 reapy 服务 将 reaper_side_enable_server.py 添加到 REAPER 操作中，并在 REAPER Studio 中运行
3. 安装软件包：

   # From PyPI
   pip install reaper_reapy_mcp
   
   # From GitHub repository
   pip install git+https://github.com/wegitor/reaper-reapy-mcp.git
   

4. 在 REAPER 中启用 Python

wheel 软件包包含所有必需的依赖项，可用于其他需要 REAPER 集成的 Python 项目。该项目使用 pyproject.toml 进行现代 Python 打包配置，从而更好地管理依赖项并配置构建系统。

示例音频文件

该应用使用示例 MP3 文件测试音频操作。需要时会自动从以下位置下载该文件：

https://www2.cs.uic.edu/~i101/SoundFiles/StarWars3.mp3

这是一个简短的《星球大战》主题曲片段，常用于测试音频应用。

运行服务

你可以直接使用 uv 运行服务：

uv --directory <project_path> run -m reaper_reapy_mcp

对于当前目录和 http MCP 模式：

uv --directory . run -m reaper_reapy_mcp --mode http

例如，在 Windows 上：

uv --directory C:\path\to\reaper_reapy_mcp run -m reaper_reapy_mcp

或者在安装后直接使用 Python 模块：

python -m reaper_reapy_mcp

HTTP 模式

使用默认设置以 HTTP 模式运行服务：

python -m reaper_reapy_mcp --mode http

使用自定义主机和端口运行：

python -m reaper_reapy_mcp --mode http --http-host example_host --http-port 3958

使用 MCP inspector 测试工具：

test_mcp.bat

可用的 MCP 工具：

音轨管理

• test_connection：验证与 REAPER 的连接
• create_track：创建新音轨
• rename_track：重命名现有音轨
• set_track_color：设置音轨颜色
• get_track_color：获取音轨颜色
• get_track_count：获取项目中的音轨数量
• get_track_list：获取所有音轨及其属性的列表

FX 管理

• add_fx：向音轨添加 FX
• remove_fx：从音轨移除 FX
• set_fx_param：设置 FX 参数值
• get_fx_param：获取 FX 参数值
• get_fx_param_list：获取 FX 参数列表
• get_fx_list：获取音轨上的 FX 列表
• get_available_fx_list：获取可用 FX 插件列表
• toggle_fx：切换 FX 的启用/禁用状态

项目控制

• set_tempo：设置项目速度
• get_tempo：获取当前速度
• get_time_signature：获取当前拍号
• set_project_time_signature：设置项目默认拍号
• set_time_signature：设置指定位置的拍号
• create_region：创建区域
• delete_region：删除区域
• create_marker：创建标记
• delete_marker：删除标记
• render_project：将项目渲染为音频文件

主音轨

• get_master_track：获取主音轨信息
• set_master_volume：设置主音轨音量
• set_master_pan：设置主音轨声像
• toggle_master_mute：切换主音轨静音状态
• toggle_master_solo：切换主音轨独奏状态

MIDI 操作

• create_midi_item：在音轨上创建空 MIDI 音频片段
  • 支持按时间（秒）和小节:节拍定位
• add_midi_note：向 MIDI 音频片段添加 MIDI 音符
• add_midi_notes：一次添加多个 MIDI 音符
• get_midi_notes：获取 MIDI 音频片段中的所有 MIDI 音符
• clear_midi_item：清除 MIDI 音频片段中的所有 MIDI 音符

音频片段操作

• insert_audio_item：将音频文件作为媒体片段插入
  • 支持按时间（秒）和小节:节拍定位
• duplicate_item：复制现有片段（MIDI 或音频）
  • 使用 REAPER 内置的复制功能，确保可靠复制
  • 支持按时间（秒）和小节:节拍定位
• get_item_properties：获取媒体片段的属性
• set_item_position：设置媒体片段的位置
  • 支持按时间（秒）和小节:节拍定位
• set_item_length：设置媒体片段的长度
• delete_item：删除媒体片段
• get_items_in_time_range：获取指定时间范围内的片段
  • 支持按时间（秒）和小节:节拍定位

片段 ID 系统

所有片段操作均使用连续索引系统（0..n）来识别片段。这使得在脚本和自动化中处理片段更加方便：

• 片段 ID 是从 0 开始的索引
• 每条音轨都有自己的片段索引序列
• 删除或重新排序片段之前，索引保持稳定
• 所有片段操作（MIDI、音频、属性）使用相同的索引系统

位置格式支持

许多 MCP 工具现在支持双位置格式，让音乐工作流更加灵活：

时间格式（秒）

{
  "start_time": 15.5,
  "new_time": 30.0
}

小节:节拍格式

{
  "start_measure": "3:2,500",
  "new_measure": "5:1,000"
}

格式："measure:beat,fraction"，其中：

• measure：从 1 开始的小节编号
• beat：从 1 开始的节拍编号
• fraction：表示节拍分数的毫秒数（000-999）
• 示例："4:2,500" = 第 4 小节、第 2 拍、半拍（500ms）

支持两种格式的工具：

• create_midi_item - 通过 start_time 或 start_measure 设置位置
• insert_audio_item - 通过 start_time 或 start_measure 设置位置
• duplicate_item - 通过 new_time 或 new_measure 设置位置
• set_item_position - 通过 new_time 或 new_measure 设置位置
• get_items_in_time_range - 通过时间或小节参数设置范围

Claude 配置（使用 uv run）：

{
    "mcpServers": {
        "reaper-reapy-mcp": {
            "type": "stdio",
            "command": "uv",
            "args": [
                "--directory",
                "<path to folder>",
                "run",
                "-m",
                "reaper_reapy_mcp"
            ]
        }
    }
}

Claude 直接配置：

{
    "mcpServers": {
        "reaper-reapy-mcp": {
            "type": "stdio",
            "command": "python",
            "args": [
                "-m",
                "reaper_reapy_mcp"
            ]
        }
    }
}

或

{
    "mcpServers": {
        "reaper-reapy-mcp": {
            "type": "stdio",
            "command": "python",
            "args": [
                "<path to folder>\\src\\reaper_reapy_mcp.py"
            ]
        }
    }
}

贡献

欢迎贡献！请随时提交 Pull Request。

许可证

本项目采用 MIT License 许可协议，详情请参阅 LICENSE 文件。