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对话。
导航
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:
| 错误键 | 含义 |
|---|---|
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有很多怪癖，现实世界的会话会很快浮出水面。
______________________________________________________________________
许可证
麻省理工学院
______________________________________________________________________
*建造于 蓝色电梯制作*