Protools MCP Server

🚀 Pro Tools MCP 服务器

Pro Tools MCP 服务器是一个基于 MCP（模型上下文协议）的服务器，它允许像 Claude 这样的 AI 助手通过 PTSL（Pro Tools 脚本库）gRPC API 来控制 Pro Tools。

⚠️ 重要提示

这是一个正在开发中的实验性项目，并非所有 Pro Tools 功能都已实现。请谨慎使用！

🚀 快速开始

只需 5 分钟，即可让项目启动并运行起来：

1. 获取 PTSL SDK - 从 Avid 下载并提取 PTSL.proto 文件。
2. 克隆并构建项目：

   git clone <repository-url>
   cd protools-mcp-server
   npm install
   npm run build
   

3. 测试连接：

   npm run test-cli -- /path/to/PTSL.proto
   

4. 配置 Claude Desktop - 将以下配置添加到 claude_desktop_config.json 文件中：

   {
     "mcpServers": {
       "protools": {
         "command": "node",
         "args": ["/absolute/path/to/protools-mcp-server/dist/index.js"],
         "env": {
           "PTSL_PROTO_PATH": "/absolute/path/to/PTSL.proto"
         }
       }
     }
   }
   

5. 重启 Claude Desktop，然后就可以开始使用 AI 控制 Pro Tools 啦！

注意：服务器默认以只读模式启动，这可以防止对会话进行任何修改，非常适合用于探索和学习。如果需要启用写操作，请参考 安全特性 部分。

✨ 主要特性

该服务器为 AI 助手提供了以下功能：

• 会话管理 - 查询会话信息、保存会话、获取全面的会话概述。
• 时间线导航 - 分页浏览轨道和剪辑、按名称搜索、在时间线上导航（仅适用于音频剪辑）。
• 轨道控制 - 列出、选择、静音、独奏和管理轨道。
• 剪辑管理 - 在时间线上查找和处理音频剪辑。
• 编辑操作 - 对时间线选择进行剪切、复制、粘贴、清除、撤销/重做操作。
• 标记管理 - 创建、列出和导航会话标记。
• 传输控制 - 播放、停止、录制和控制播放。
• 视觉分析 - 生成波形图像并分析音频内容（起始点、峰值、静音检测）。
• 原始 PTSL 访问 - 发送自定义 PTSL 命令以实现高级用例。
• 诊断功能 - 测试和验证 PTSL 连接状态。

已知限制

• MIDI 剪辑：由于 PTSL API 的限制，时间线索引仅能捕获音频剪辑，无法查询 MIDI 剪辑的位置。虽然可以在剪辑列表中看到 MIDI 剪辑，但无法获取其在时间线上的位置。

📦 安装指南

npm install
npm run build

💻 使用示例

Claude Desktop（推荐）

要在 Claude Desktop 中使用 MCP 服务器，需将其添加到 Claude Desktop 配置文件中：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "protools": {
      "command": "node",
      "args": ["/absolute/path/to/protools-mcp-server/dist/index.js"],
      "env": {
        "PTSL_PROTO_PATH": "/absolute/path/to/PTSL.proto"
      }
    }
  }
}

macOS 示例：

{
  "mcpServers": {
    "protools": {
      "command": "node",
      "args": ["/Users/username/protools-mcp-server/dist/index.js"],
      "env": {
        "PTSL_PROTO_PATH": "/Users/username/protools-mcp-server/ptsl_sdk/Source/PTSL.proto"
      }
    }
  }
}

添加配置后：

1. 重启 Claude Desktop。
2. 确保 Pro Tools 正在运行。
3. 向 Claude 提出 Pro Tools 相关任务请求！

Claude Cowork（实验性/未测试）

⚠️ 重要提示

Cowork 连接器尚未经过广泛测试，建议使用 Claude Desktop。

Claude Cowork 需要使用 HTTPS。服务器将使用自签名 SSL 证书进行本地开发。

1. 启动 HTTPS 服务器：

   export PTSL_PROTO_PATH=/path/to/PTSL.proto
   ./start-cowork.sh
   

2. 在 Claude Cowork 中操作：
   • 点击“添加自定义连接器”。
   • 名称：Pro Tools。
   • 远程 MCP 服务器 URL：https://localhost:3000/sse。
   • 点击“添加”。
   • 接受安全警告（自签名证书在本地主机上是安全的）。

自定义端口：

PORT=3443 PTSL_PROTO_PATH=/path/to/PTSL.proto npm run start:http
# 然后使用：https://localhost:3443/sse

示例用例

以下是一些可以让 Claude 对 Pro Tools 会话执行的操作：

• 分析与导航：
  • “显示从 1 分钟到 1 分 30 秒的人声轨道波形”。
  • “查找主音轨中所有持续时间超过 1 秒的静音部分”。
  • “在第 8 小节到第 16 小节之间的底鼓轨道中，鼓点在哪里？”
  • “在 30 秒到 1 分钟之间的时间线上有哪些剪辑？”
• 编辑与组织：
  • “在主音轨的每个声乐乐句处创建标记”。
  • “找到名为 'Guitar Solo 3' 的剪辑并选中它”。
  • “静音所有鼓轨”。
  • “复制所选内容并粘贴到 2 分钟处”。
• 会话管理：
  • “当前会话的名称和采样率是多少？”
  • “列出我会话中的所有轨道”。
  • “保存会话”。
• 播放控制：
  • “从 1 分钟播放到 1 分 30 秒”。
  • “停止播放”。
  • “开始录制”。

📚 详细文档

安全特性

服务器采用了细粒度权限系统来保护你的 Pro Tools 会话。默认情况下，它以只读模式运行，并启用了安全的音频分析功能。

默认权限（无需配置）

• 始终允许的操作：
  • 读取操作（查询、轨道列表、剪辑信息、会话信息）。
  • 播放控制（播放、停止、切换）。
  • UI 状态更改（静音/独奏、时间线选择、编辑工具）。
  • 复制到剪贴板（非破坏性操作）。
  • 仅导出音频到临时目录（启用音频分析）。
• 默认阻止的操作（需要设置 ALLOW_WRITES 才能启用）：
  • 创建/编辑标记 (memory)。
  • 剪切/粘贴/清除操作 (clipboard)。
  • 导出到自定义路径 (export)。
  • 创建/删除轨道 (track_structure)。
  • 保存/打开会话 (session)。
  • 录制 (recording)。

启用写操作

使用 ALLOW_WRITES 环境变量来启用特定的权限组：

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json)：

{
  "mcpServers": {
    "protools": {
      "command": "node",
      "args": ["/absolute/path/to/protools-mcp-server/dist/index.js"],
      "env": {
        "PTSL_PROTO_PATH": "/absolute/path/to/PTSL.proto",
        "ALLOW_WRITES": "memory,clipboard"
      }
    }
  }
}

命令行：

# 允许标记和剪贴板编辑
ALLOW_WRITES=memory,clipboard PTSL_PROTO_PATH=/path/to/PTSL.proto node dist/index.js

# 允许所有操作（谨慎使用）
ALLOW_WRITES=all PTSL_PROTO_PATH=/path/to/PTSL.proto node dist/index.js

权限组

组	操作	风险级别
memory	创建/编辑/删除标记	🟢 安全
export	将音频导出到任何位置	🟡 中等
clipboard	剪切/粘贴/清除音频	🟠 有破坏性
track_structure	创建/删除轨道	🟠 有破坏性
session	保存/打开/关闭会话	🔴 高
recording	录制音频	🔴 高

AI 音频分析

由于像 Claude 这样的 AI 模型无法直接收听音频，因此该服务器提供了几种方法，通过视觉和文本分析帮助 AI “理解”音频内容。analyze_audio 工具可以对 Pro Tools 会话中的任何区域进行渲染并以多种方式进行分析：

分析模式

• 隔离模式：通过独奏单个轨道、渲染该区域并生成分析结果，非常适合检查单个乐器或人声。
• 混音模式：分析 Pro Tools 中当前混音的完整效果，考虑所有静音/独奏状态、自动化和插件处理。

分析类型

1. 波形可视化 生成高分辨率的波形图像，显示振幅随时间的变化。可视化内容包括：
   • 立体声通道分别显示（上/下）。
   • 以 Pro Tools 时间码格式显示的时间标记（HH:MM:SS:FF）。
   • 以 dB 为单位的振幅刻度（-24dB 到 0dB 参考）。
   • 用于视觉定位的网格线。

用例：识别剪辑边界、查看动态、发现静音或响亮部分、理解节奏模式。

示例波形输出（4096x2048 像素）：

2. 频谱图可视化 生成频率频谱可视化图像，显示频率内容随时间的变化。颜色表示每个频率处的振幅。

用例：识别频率范围、发现谐波、查看音调与打击乐内容、检测共振。

示例频谱图输出（2048x1024 像素）：

3. 峰值/RMS 分析 提供所选音频区域的整体振幅统计信息。

用例：检查整体电平、了解平均响度、验证动态余量。

示例峰值分析输出：

**整体音频统计信息：**
RMS 电平：-27.46 dB
峰值电平：-12.09 dB

这表示整个所选区域的平均响度（RMS）和最大峰值。

4. 事件/起始点检测 使用 Aubio 库检测瞬态和节奏事件（鼓击、音符起始等）。

用例：查找编辑的击打点、理解节奏、为标记放置识别节拍。

示例事件检测输出：

**事件/起始点分析**

模式：混音
时间范围：00:00:10:00 - 00:00:15:00
检测到的事件：24

**起始时间：**
1. 00:00:10:02（样本 480,960）
2. 00:00:10:17（样本 488,160）
3. 00:00:11:02（样本 495,360）
4. 00:00:11:17（样本 502,560）
...

5. 静音检测 根据可配置的阈值和持续时间检测静音或低电平音频时段。

用例：查找录制片段之间的间隙、识别清理机会、检测段落边界。

参数：

• silence_threshold_db：振幅阈值（默认：-40dB）
• silence_min_duration：最小持续时间（秒）（默认：0.3s）

示例静音检测输出：

**静音分析**

模式：隔离（轨道：主音轨）
时间范围：00:00:00:00 - 00:01:00:00
阈值：-40dB，最小持续时间：0.3s
检测到的静音时段：8

**静音时段：**
1. 00:00:05:12 - 00:00:08:23（3.37s）
   样本：259,200 - 421,440
2. 00:00:19:04 - 00:00:20:15（1.50s）
   样本：915,840 - 988,800
...

6. 综合分析 一次性运行所有可用的基于文本的分析（峰值、事件和静音），提供音频内容的全面概述。

用例：初步探索不熟悉的音频、在进行编辑决策之前获取完整上下文。

7. 原始音频传输 将一个区域渲染为 WAV 格式，并以 base64 编码数据返回（由于 MCP 消息大小限制，限制为 10 秒）。

用例：存档、外部处理或与支持音频的 AI 模型未来使用。

注意：Claude 和大多数当前的 AI 模型无法直接分析音频文件。此模式是为了未来兼容性和外部工具集成而包含的。

要求

• ffmpeg：波形、频谱图、峰值和静音检测所需。
  • 安装：brew install ffmpeg（macOS）或 apt-get install ffmpeg（Linux）
• aubio：事件/起始点检测所需。
  • 安装：brew install aubio（macOS）或 apt-get install aubio（Linux）

服务器将自动检测哪些工具可用，并在缺少所需依赖项时提供相应的错误消息。

可用工具

MCP 服务器提供了跨多个类别的 36 种工具：

会话管理

• get_session_info - 获取当前会话的名称、路径和采样率。
• get_session_length - 获取会话的总时长。
• get_session_overview - 获取全面的会话信息。
• save_session - 保存当前会话。

轨道管理

• get_track_list - 列出所有轨道及其属性。
• select_tracks - 按名称或模式选择轨道。
• set_track_mute - 静音/取消静音轨道。
• set_track_solo - 独奏/取消独奏轨道。

时间线与剪辑

• refresh_pro_tools_index - 使时间线缓存与 Pro Tools 会话同步。
• get_timeline_tracks - 分页浏览轨道。
• get_timeline_clips - 分页浏览剪辑。
• search_timeline - 按名称搜索轨道/剪辑。
• get_clip_list - 列出剪辑库中的剪辑。
• select_clip_on_timeline - 在时间线上选择特定的剪辑。
• get_timeline_selection - 获取当前时间线选择范围。
• set_timeline_selection - 将时间线选择设置为特定的时间范围。

传输控制

• play - 开始播放。
• stop - 停止播放/录制。
• toggle_play - 切换播放/停止状态。
• record - 开始录制。
• set_playback_mode - 配置循环/动态传输模式。

编辑操作

• cut - 剪切所选音频。
• copy - 复制所选音频。
• paste - 从剪贴板粘贴。
• clear - 清除/删除所选音频。
• undo - 撤销上一次操作。
• redo - 重做上一次撤销的操作。

标记管理

• get_markers - 列出所有内存位置/标记。
• create_marker - 在指定时间创建新标记。
• edit_marker - 修改现有标记的名称/时间。
• delete_marker - 删除特定标记。
• delete_all_markers - 删除所有标记。
• select_marker - 导航到并选择一个标记。

音频分析

• analyze_audio - 使用多种分析类型分析音频区域：
  • 波形可视化
  • 频谱图（频率分析）
  • 峰值/RMS 振幅数据
  • 事件/起始点检测（需要 aubio）
  • 静音检测
  • 综合分析
  • 原始音频传输

高级/诊断

• ptsl_command - 直接发送原始 PTSL 命令。
• sample_ptsl_responses - 查看示例 PTSL API 响应。

开发

# 安装依赖项
npm install

# 构建 TypeScript
npm run build

# 测试 PTSL 连接
npm run test-cli -- /path/to/PTSL.proto

# 测试 MCP 服务器
export PTSL_PROTO_PATH=/path/to/PTSL.proto
./test-mcp.sh
./test-tools.sh

# 测试写保护安全机制
node test-write-protection.js                           # 测试只读模式
ALLOW_WRITE_OPERATIONS=true node test-write-protection.js  # 测试启用写操作

项目结构

protools-mcp-server/
├── src/
│   ├── index.ts              # MCP 服务器入口点
│   ├── test-cli.ts           # 用于 PTSL 连接的测试 CLI
│   ├── grpc/
│   │   ├── client.ts         # PTSL gRPC 客户端包装器
│   │   └── commands.ts       # CommandId 枚举
│   ├── tools/                # MCP 工具（待确定）
│   └── resources/            # MCP 资源（待确定）
├── package.json
├── tsconfig.json
└── README.md

架构

用户请求（Claude/AI）
    ↓
MCP 服务器（TypeScript - 本项目）
    ↓
gRPC 客户端（从用户的 PTSL.proto 生成）
    ↓
Pro Tools PTSL 服务器（localhost:31416）
    ↓
Pro Tools 应用程序

项目状态与路线图

运行良好的功能

• ✅ 基本会话管理（信息、保存、导航）
• ✅ 轨道控制（列出、选择、静音、独奏）
• ✅ 时间线导航和搜索（仅适用于音频剪辑）
• ✅ 传输控制（播放、停止、录制）
• ✅ 基本编辑操作（剪切、复制、粘贴、清除、撤销/重做）
• ✅ 标记管理（创建、列出、编辑、删除、导航）
• ✅ 音频分析（波形、频谱图、峰值、事件、静音检测）
• ✅ 时间线选择管理

已知问题与限制

• ⚠️ 由于 PTSL API 限制，无法对 MIDI 剪辑的时间线位置进行索引。
• ⚠️ 一些高级 Pro Tools 功能尚未通过 PTSL 公开。
• ⚠️ 音频分析需要外部依赖项（ffmpeg、aubio）。
• ⚠️ 由于 MCP 消息大小限制，原始音频传输限制为 10 秒。

潜在的未来增强功能

• 🔮 插件参数控制
• 🔮 自动化读写
• 🔮 发送/辅助路由管理
• 🔮 输入/输出配置
• 🔮 混音器快照
• 🔮 批量处理操作
• 🔮 会话模板创建
• 🔮 扩展 MIDI 支持（如果 PTSL API 扩展）

故障排除

"Failed to connect to PTSL server"

• 确保 Pro Tools 正在运行。
• 验证 Pro Tools 首选项中是否启用了 PTSL。
• 检查是否有其他程序正在使用端口 31416。

"Request refused. Use the RegisterConnection command first"

• 这通常意味着 Pro Tools 没有运行。
• 尝试重启 Pro Tools。

"SDK_VersionMismatch: The client and host interface versions are incompatible"

• 确保使用的是正确的 PTSL.proto 版本。
• proto 版本应与你的 Pro Tools 版本匹配。
• 如果需要，从 Avid 下载匹配的 SDK。

Proto 文件错误

• 确保使用的是正确的 PTSL.proto 版本。
• proto 文件应与你的 Pro Tools 版本匹配。
• 如果需要，从 Avid 下载最新的 SDK。

贡献

欢迎为项目做出贡献！以下是你可以提供帮助的方式：

报告问题

• 使用 GitHub Issues 报告错误或请求功能。
• 包括 Pro Tools 版本、PTSL SDK 版本和操作系统详细信息。
• 如果报告行为问题，请提供会话详细信息。
• 适当时，包括错误消息和日志。

贡献代码

1. 分叉仓库。
2. 创建功能分支 (git checkout -b feature/amazing-feature)。
3. 进行更改并彻底测试。
4. 遵循现有的代码风格（TypeScript、ESLint）。
5. 根据需要更新文档。
6. 提交更改 (git commit -m 'Add amazing feature')。
7. 推送到你的分支 (git push origin feature/amazing-feature)。
8. 打开拉取请求。

开发指南

• 所有新工具应遵循 src/tools/ 中的现有工具结构。
• 添加适当的错误处理和验证。
• 为公共 API 包含 JSDoc 注释。
• 尽可能使用真实的 Pro Tools 会话进行测试。
• 如果添加了新功能，请更新 README。

测试

在提交 PR 之前，请确保：

npm run build          # 构建成功
npm run test-cli       # PTSL 连接正常
./test-mcp.sh          # MCP 服务器初始化正常
./test-tools.sh        # 工具注册正常

📄 许可证

本项目采用 MIT 许可证，请参阅 LICENSE 文件获取详细信息。

致谢

Pro Tools 和 PTSL 是 Avid Technology, Inc. 的商标。这是一个独立的开源项目，与 Avid 没有关联或得到其认可。

支持与社区

• 问题反馈：通过 GitHub Issues 报告错误和请求功能。
• 讨论交流：在 GitHub Discussions 中提问和分享工作流程。
• PTSL 文档：参考 Avid SDK 中的官方 PTSL 文档。

本项目是实验性的且由社区驱动。通过贡献代码、报告问题或分享使用案例，帮助我们把项目变得更好！