Pro Tools Mcp

protools-mcp

由 Claude 和 Model Context Protocol 驱动的 Avid Pro Tools 自然语言接口。

protools-mcp 是一个本地 MCP (Model Context Protocol) 服务，可通过 PTSL (Pro Tools Scripting Library) API 将 Claude——或任何兼容 MCP 的 AI 助手——连接到正在运行的 Pro Tools 会话。无需浏览菜单或编写脚本，只需用日常语言描述需求，Claude 就会直接在会话中为你处理。

它专为播客后期制作工作流打造，同样适用于音乐制作、广播和音频后期制作。

---

实际使用示例

连接后，你可以这样对话：

“这个会话里有什么内容？” “搜索文字稿，找出嘉宾提到气候变化的所有地方。” “在 00:14:32:00 处设置一个名为‘Act Two’的标记。” “将所有音乐轨道静音，并独奏主持人轨道。” “时间线 22 到 35 分钟之间有哪些片段？” “将此会话另存为新版本，名称为 EP47_mix_v2。” “将对白轨道导出为 AAF 到交付文件夹。”

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

---

功能

提供 7 个功能组中的 25+ 个工具：

分组	工具	说明
会话	get_session_info, get_markers, get_track_list, get_session_snapshot, get_show_profile	会话元数据、轨道、标记和节目配置
轨道	get_track_edl, get_track_playlists, get_clips_in_range	片段级详情、播放列表和时间范围查询
文字稿	get_transcript, search_transcript, get_transcript_for_range	带上下文和说话人标签的语音转文字 CSV 搜索
导航	get_playhead_position, get_current_selection, set_playhead	播放头和所选内容状态
编辑	select_region, create_marker, mute_track, unmute_track, solo_track, consolidate_clip	修改会话（Claude 会在执行前确认）
会话管理	save_session, close_session, open_session, save_session_as	保存、关闭、打开会话和创建会话版本
导出	export_tracks_as_aaf	AAF 导出，可配置格式、位深和复制选项

可选的 节目配置 系统让你为每档节目定义配置——主持人姓名、轨道布局、命名惯例——为 Claude 提供必要上下文，使其能够智能地处理多档节目。

---

前置条件

• Pro Tools 正在运行的 macOS（PTSL 监听 localhost:31416）
• Python 3.11+（已使用 3.11 测试）
• 已全局安装或安装在虚拟环境中的 py-ptsl
• Claude Desktop 或 Claude Code（用于 MCP 集成）
• Claude/终端的 辅助功能权限（AAF 导出对话框自动化所需）

---

设置

1. 克隆此仓库：

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

2. 创建虚拟环境：

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

   --system-site-packages 标志会复用系统范围内安装的 py-ptsl 和 grpcio。

3. 配置 .env（可选——显示默认值）：

   PTSL_HOST=localhost
   PTSL_PORT=31416
   

4. 添加节目配置（可选）： 将 JSON 文件放入 show_profiles/。格式请参见 show_profiles/holy_uncertain.json。

5. 注册到 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 Desktop Chat、Cowork 和 Code 会话中使用。

   仅用于 Claude Code CLI 时，请使用：

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

6. 授予辅助功能访问权限（AAF 导出自动化所需）： 系统设置 > 隐私与安全性 > 辅助功能——启用 Claude Desktop 和/或你的终端应用。

7. 打开 Pro Tools 并载入一个会话。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]。Claude 会说明操作并在执行前确认。

• 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) — 将音轨设为独奏。
• 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) — 打开 .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（默认）— 强制启用 Media Composer 兼容性
  • 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

• PTSLBridge — 延迟建立 gRPC 连接，并自动重新连接。@ptsl_command 装饰器统一处理错误。自定义 Operation 子类用于处理 py-ptsl 的 ops 模块中没有的 PTSL 命令。
• TranscriptWatcher — 基于文件状态信息的 CSV 缓存。仅当文件的 mtime 发生变化时才重新加载。通过搜索会话目录自动发现 CSV 文件。
• ShowProfileLoader — 在启动时读取一次 show_profiles/*.json，并按名称前缀匹配会话。
• osascript integration — 对于会触发 Pro Tools 对话框的 PTSL 命令（例如 AAF 导出），桥接程序会在后台线程中运行命令，并使用 System Events 自动关闭对话框。需要辅助功能权限。

---

错误处理

所有 PTSL 错误都会先返回结构化字典，再作为 ToolError 引发：

错误键	含义
ptsl_unavailable	Pro Tools 未运行或 gRPC 连接已断开
no_session	Pro Tools 中没有打开会话
ptsl_command_error	PTSL 命令失败（详情见消息）
no_transcript	未找到或未配置转录 CSV 文件
dialog_waiting	AAF 导出对话框需要手动确认（未授予辅助功能权限）

---

实现说明

• 时间码格式：Pro Tools 使用 HH:MM:SS:FF。标记在内部返回原始采样位置；桥接程序使用 samples_to_timecode(samples, sample_rate, fps) 进行转换。
• 音轨的 active 字段：根据 TrackAttributes 上的 is_inactive == TAState_None 派生。与静音/隐藏状态不同。
• EDL 文本：解析 Pro Tools 导出的制表符分隔文本，列包括：CHANNEL、EVENT、CLIP NAME、START TIME、END TIME、DURATION、STATE。
• Pro Tools 特性：SaveSessionAs 和目录路径需要以 / 结尾。一些命令（GetTrackPlaylists、GetPlaylistElements）需要以 CId_ 为前缀的命令 ID。必须从 JSON 中剔除空的 track_id 字段，以避免出现“only one of track_id/track_name”错误。
• 连接管理：gRPC 连接可能在两次调用之间变得过期。@ptsl_command 装饰器会捕获 grpc.RpcError 并自动重置连接。

---

故障排除

• “Pro Tools 未运行” — 确保 Pro Tools 已打开并加载了会话。PTSL 监听端口 31416。
• 未找到转录 — 在你的节目配置文件中设置 transcript_export_path，或将 CSV 文件放在会话文件旁边。
• 数据过期 — EDL 缓存会在 30 秒后过期。转录会在文件修改后重新加载。再次调用工具以获取最新数据。
• AAF 导出卡住 — 在“系统设置”>“隐私与安全性”>“辅助功能”中，为运行 MCP 服务的应用授予辅助功能权限。
• “only one of track_id and track_name” — 通过自定义 Operation 上的 json_messup() 覆盖在内部处理。

---

参与贡献

欢迎提交问题和拉取请求。如果你在特定工作流中使用此工具并遇到边缘情况，请提交问题——Pro Tools 有许多特性，实际会话很快就会暴露这些问题。

---

许可证

MIT

---

由 Blue Elevator Productions 构建