使用说明

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+个工具：

组	工具	描述
会话	`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就有了在多个节目中智能工作所需的上下文。

先决条件

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

设置

克隆此存储库：

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

创建虚拟环境：

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 安装。

配置 .env （可选--显示默认值）：
```
PTSL_HOST=localhost
PTSL_PORT=31416
```
添加节目简介 （可选）：将JSON文件放入 show_profiles/。参见 show_profiles/holy_uncertain.json 对于格式。

在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

授予无障碍访问权限 （AAF出口自动化所需）：系统设置>隐私和安全>辅助功能-启用Claude Desktop和/或您的终端应用程序。
打开专业工具 加载了会话。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 对话。

编辑操作（写入）

所有写入工具都有标签 [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:

错误键	含义
`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 领域：源自 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有很多怪癖，现实世界的会话会很快浮出水面。

许可证

麻省理工学院

建造于蓝色电梯制作

使用说明

protools mcp

它在实践中是什么样子的

能力

先决条件

设置

工具参考

会话上下文（只读）

轨道详细信息（只读）

成绩单（只读）

导航

编辑操作（写入）

会话管理（写）

导出（写入）

成绩单支持

显示配置文件格式

建筑

错误处理

实现注意事项

故障排除

贡献

许可证

相关 MCP

Flomo笔记服务

3D资产生成服务

文档搜索服务

Microsoft 365命令行管理服务器

AI文本人性化服务

APISIX MCP服务器