Pro Tools Mcp

protools-mcp

Claude と Model Context Protocol を活用した、Avid Pro Tools 用の自然言語インターフェースです。

protools-mcp は、Claude、または MCP 対応のあらゆる AI アシスタントを、PTSL（Pro Tools Scripting Library）API を介して起動中の Pro Tools セッションに接続するローカルの MCP（Model Context Protocol） サーバーです。メニューを操作したりスクリプトを書いたりする代わりに、必要なことを自然な言葉で伝えれば、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 は複数の番組をまたいで適切に作業するためのコンテキストを得られます。

---

前提条件

• macOS で Pro Tools が起動していること（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 デコレーターがエラーを一律に処理します。py-ptsl の ops モジュールにない PTSL コマンドには、カスタムの Operation サブクラスを使用します。
• TranscriptWatcher — stat ベースの CSV キャッシュです。ファイルの mtime が変更された場合にのみ再読み込みします。セッションディレクトリを検索して CSV を自動検出します。
• ShowProfileLoader — 起動時に show_profiles/*.json を一度読み込み、名前のプレフィックスでセッションを照合します。
• osascript integration — AAF の書き出しなど、Pro Tools のダイアログを表示する PTSL コマンドでは、ブリッジがバックグラウンドスレッドでコマンドを実行し、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 が必要です。「only one of track_id/track_name」エラーを避けるため、空の track_id フィールドは JSON から削除する必要があります。
• 接続管理：gRPC 接続は呼び出しの間に無効になることがあります。@ptsl_command デコレーターは grpc.RpcError を捕捉し、接続を自動的にリセットします。

---

トラブルシューティング

• 「Pro Tools is not running」 — Pro Tools がセッションを読み込んだ状態で開いていることを確認してください。PTSL はポート 31416 で待ち受けます。
• トランスクリプトが見つからない — show profile に transcript_export_path を設定するか、セッションファイルと同じ場所に CSV を配置してください。
• データが古い — EDL キャッシュは 30 秒後に期限切れになります。トランスクリプトはファイルの変更時に再読み込みされます。最新のデータを取得するには、ツールを再度呼び出してください。
• AAF の書き出しが停止する — MCP サーバーを実行しているアプリに対し、「システム設定」>「プライバシーとセキュリティ」>「アクセシビリティ」でアクセシビリティへのアクセスを許可してください。
• 「only one of track_id and track_name」 — カスタム Operation の json_messup() オーバーライドによって内部的に処理されます。

---

コントリビューション

Issue とプルリクエストを歓迎します。特定のワークフローで使用していて想定外のケースに遭遇した場合は、Issue を作成してください。Pro Tools には多くの注意点があり、実際のセッションではすぐに表面化します。

---

ライセンス

MIT

---

Blue Elevator Productions によって作成