Protools MCP

protools mcp

Avid Pro Tools的自然语言界面，由Claude和模型上下文协议提供支持。

protools mcp是一个本地 MCP（模型上下文协议） 通过PTSL（专业工具脚本库）API将Claude或任何兼容MCP的人工智能助手连接到实时专业工具会话的服务器。您不用导航菜单或编写脚本，而是用通俗易懂的语言描述所需内容，Claude可以在会话中直接处理。

它专为播客后期制作工作流程而构建，在音乐制作、广播和音频后期同样适用。

______________________________________________________________________

它在实践中是什么样子的

连接后，您可以进行以下对话：

*“这次会议有什么内容？”* *“在记录中搜索客人提到气候变化的所有地方。”* *“在00:14:32:00设置一个标记，称为“第二幕”。”* *“将所有音乐曲目静音，并由主持人独唱。”* *“时间线上22到35分钟之间有哪些剪辑？”* *“保存名为EP47_mix_v2的此会话的新版本。”* *“将对话曲目作为AAF导出到传送文件夹。”*

Claude读取您的实时会话状态，回答有关时间线的问题，并直接在Pro Tools中执行写入操作——无需脚本、无需键盘快捷键、无需菜单跳转。

______________________________________________________________________

能力

7个职能组的25+个工具：

可选 显示个人资料 该系统允许您定义每个节目的配置——主机名、曲目布局、命名约定——这样Claude就有了在多个节目中智能工作所需的上下文。

______________________________________________________________________

先决条件

• macOS Pro Tools正在运行（PTSL正在监听 localhost:31416)
• Python 3.11+ （用3.11测试）
• py-ptsl 在系统范围内或虚拟环境中安装
• 克劳德桌面版 或 克劳德代码 （用于MCP集成）
• 无障碍权限 用于Claude/terminal（AAF导出对话框自动化所需）

______________________________________________________________________

设置

1. 克隆此存储库：

   git clone https://github.com/BlueElevatorProductions/protools-mcp.git
   cd protools-mcp

1. 创建虚拟环境：

   python3 -m venv venv --system-site-packages
   source venv/bin/activate
   pip install -r requirements.txt --no-cache-dir

这 --system-site-packages flag在整个系统中重用 py-ptsl 和 grpcio 安装。

1. 配置 .env （可选--显示默认值）：

   PTSL_HOST=localhost
   PTSL_PORT=31416

1. 添加节目简介 （可选）：

将JSON文件放入 show_profiles/。参见 show_profiles/holy_uncertain.json 对于格式。

1. 在Claude Desktop注册 --添加到 ~/Library/Application Support/Claude/claude_desktop_config.json:

   {
     "mcpServers": {
       "protools-mcp": {
         "command": "/path/to/protools-mcp/venv/bin/python",
         "args": ["/path/to/protools-mcp/server.py"]
       }
     }
   }

这使得服务器在Claude桌面聊天、协作和代码会话中可用。

对于 仅限Claude代码CLI，使用：

   claude mcp add protools-mcp -s user -- /path/to/protools-mcp/venv/bin/python /path/to/protools-mcp/server.py

1. 授予无障碍访问权限 （AAF出口自动化所需）：

系统设置>隐私和安全>辅助功能-启用Claude Desktop和/或您的终端应用程序。

1. 打开专业工具 加载了会话。MCP服务器在第一次工具调用时延迟连接。

______________________________________________________________________

工具参考

会话上下文（只读）

• get_session_snapshot() --组合：会话信息+标记+曲目+自动匹配的节目简介。 从这里开始。 在任何会话开始时呼叫的最佳工具。
• get_session_info() --会话名称、路径、采样率、比特深度、时间码格式、曲目计数、音频文件计数。
• get_markers() --所有带有索引、名称、时间码和注释的内存位置标记。
• get_track_list(filter="all") --具有活动、静音、独奏和隐藏状态的曲目。筛选器： all, active, audio, inactive.
• get_show_profile(show_id?) --返回显示配置文件配置。如果没有给出ID，则自动从会话名称前缀推断。

轨道详细信息（只读）

• get_track_edl(track_name) --曲目的完整剪辑列表：剪辑名称、开始/结束时间码、持续时间、状态。
• get_track_playlists(track_name) --曲目上的所有播放列表，包括不活动的替代曲目。
• get_clips_in_range(start_timecode, end_timecode, track_filter?) --在时间码范围内跨曲目的所有剪辑。

成绩单（只读）

• get_transcript() --Pro Tools语音转文本CSV导出的完整转录。
• search_transcript(query, track_filter?, start_timecode?, end_timecode?) --使用2行上下文窗口进行关键字搜索。
• get_transcript_for_range(start_timecode, end_timecode) --时间范围内的转录行，格式为 SPEAKER: text 对话。

导航

• get_playhead_position() --当前播放头时间码。
• get_current_selection() --开始、结束、持续时间和所选曲目名称。
• set_playhead(timecode) --将播放头移动到指定的时间码。

编辑操作（写入）

所有写入工具都有标签 [WRITE]克劳德将描述操作并在执行前确认。

• select_region(start_timecode, end_timecode, track_names?) --设置时间线选择。非破坏性。
• create_marker(name, timecode, comment?) --在指定的时间码处添加内存位置标记。
• mute_track(track_name) / unmute_track(track_name) --切换曲目静音状态。
• solo_track(track_name) --Solos是一条赛道。
• consolidate_clip(track_name, start_timecode, end_timecode) --将一个区域合并到一个剪辑中。 在磁盘上创建新的音频文件。

会话管理（写）

• save_session() --将当前会话保存到磁盘。
• save_session_as(session_name, session_location) --以新名称保存。 session_name 是不带扩展名的文件名； session_location 是目标目录。
• close_session(save_before_close=True) --关闭会话，可选择先保存。
• open_session(session_path) --打开a .ptx 或 .ptf 会话文件。

导出（写入）

• export_tracks_as_aaf(...) --将所选曲目导出为AAF。通过osascript自动处理Pro Tools文件夹对话框。

- audio_format: WAV （默认）， AIFF, MXF, Embedded - bit_depth: 24 （默认）， 16 - copy_option: copy （默认）， consolidate, link - quantize_to_frame: true （默认） - avid_compatible: false （默认）--强制媒体编辑器兼容性 - stereo_as_multichannel: false （默认） - sequence_name：默认为 file_name

______________________________________________________________________

成绩单支持

转录工具希望在会话旁边有一个Pro tools语音转文本CSV导出。将CSV放入会话目录（或设置 transcript_export_path 在您的节目简介中），服务器将自动发现它。它在文件修改时重新加载，因此当您迭代转录时，数据保持最新。

______________________________________________________________________

显示配置文件格式

节目简介让Claude了解特定节目的结构——哪些曲目属于哪些演讲者、命名约定以及导出的位置。将JSON文件放入 show_profiles/。配置文件通过会话名称前缀自动匹配。

{
  "show_id": "HU",
  "show_name": "Holy Uncertain",
  "session_name_prefix": "HU-",
  "hosts": ["Chris", "Lauren"],
  "dialogue_tracks": ["Chris", "Lauren Int R", "Chris Int R"],
  "guest_tracks": ["Randy Int R"],
  "music_tracks": ["Music"],
  "transcript_export_path": "/path/to/episodes/",
  "naming_conventions": {
    "session": "HU-{episode_number}-{guest_last_name}-V{version}",
    "export": "HU-{episode_number}-{guest_last_name}-MIX-V{version}"
  }
}

______________________________________________________________________

建筑

Claude Desktop  ──stdio──▶  server.py (FastMCP)
                                  │
                    ┌─────────────┼─────────────┐
                    ▼             ▼             ▼
              PTSLBridge    Transcript     ShowProfile
              (gRPC)        Watcher        Loader
                  │             │              │
                  ▼             ▼              ▼
              Pro Tools     CSV files      JSON files
              :31416

• PTSL桥 --具有自动重新连接功能的延迟gRPC连接。这 @ptsl_command 装饰器统一处理错误。自定义 Operation 子类涵盖了不在py-PTSL操作模块中的PTSL命令。
• 成绩单观察者 --基于统计的CSV缓存。仅当文件 mtime 变化。通过搜索会话目录自动发现CSV。
• ShowProfileLoader --阅读 show_profiles/*.json 启动时，按名称前缀匹配会话。
• osascript集成 --对于触发Pro Tools对话框的PTSL命令（例如AAF导出），网桥在后台线程中运行该命令，并使用系统事件自动关闭对话框。需要无障碍权限。

______________________________________________________________________

错误处理

所有PTSL错误在引发之前都会返回结构化字典 ToolError:

______________________________________________________________________

实现注意事项

• 时间码格式：Pro Tools使用 HH:MM:SS:FF标记在内部返回原始样本的位置；桥梁转换使用 samples_to_timecode(samples, sample_rate, fps).
• 轨道 active 领域：源自 is_inactive == TAState_None 上 TrackAttributes不同于静音/隐藏。
• EDL文本：从Pro Tools的以制表符分隔的文本导出中解析，其中包含列： CHANNEL, EVENT, CLIP NAME, START TIME, END TIME, DURATION, STATE.
• 专业工具怪癖: SaveSessionAs 目录路径需要尾随 /.一些命令(GetTrackPlaylists, GetPlaylistElements)需要 CId_-前缀命令ID。空 track_id 必须从JSON中删除字段，以避免“只有一个track_id/track_name”错误。
• 连接管理：gRPC连接可能会在调用之间失效。这 @ptsl_command 装饰工抓 grpc.RpcError 并自动重置连接。

______________________________________________________________________

故障排除

• “Pro Tools未运行” --确保Pro Tools已打开并加载了会话。PTSL在端口上监听 31416.
• 未找到成绩单 --设置 transcript_export_path 在您的节目配置文件中，或将CSV放在会话文件旁边。
• 陈旧数据 --EDL缓存将在30秒后过期。修改文件时重新加载成绩单。再次调用工具以获取新数据。
• AAF出口挂起 --在“系统设置”>“隐私与安全”>“辅助功能”中为运行MCP服务器的应用程序授予辅助功能访问权限。
• “只有track_id和track_name中的一个” --由内部人员处理 json_messup() 覆盖自定义操作。

______________________________________________________________________

贡献

欢迎问题和拉取请求。如果你在特定的工作流程中使用它并遇到边缘情况，请打开一个问题——Pro Tools有很多怪癖，现实世界的会话会很快浮出水面。

______________________________________________________________________

许可证

麻省理工学院

______________________________________________________________________

*建造于 蓝色电梯制作*