MCP Server for Autodesk ShotGrid REST API

Autodesk ShotGrid REST API 用 MCP サーバー

このプロジェクトは、FastMCP を使用して実装された MCP（Model Context Protocol）サーバーを提供し、LLM エージェントが REST API を介して Autodesk ShotGrid とプログラムで連携できるようにします。プロジェクト、アセット、タスク、ユーザー、ノートなどの ShotGrid エンティティを照会および管理するためのツール群を公開します。LLM ベースのワークフローとの連携に向けて、transport="stdio" モードをサポートしています。

機能

• OAuth2 認証を使用して Autodesk ShotGrid に接続します。
• FastMCP を使用して ShotGrid REST API の操作を MCP ツールとして公開します。
• プロジェクト、ユーザー、アセット、タスク、ノート、バージョン、ブッキングなどを照会します。
• エンティティの詳細情報を取得します。
• LLM ベースのワークフローとの連携を想定して設計されています。
• モジュール化されたコードベースです。main.py は MCP サーバーと主要なツール定義を提供し、booking_tools.py はすべての Booking CRUD 操作を処理し、note_tools.py は Note／Reply の CRUD 操作と添付ファイルの読み取りを処理し、shotgrid_rest.py は ShotGrid API ラッパーを実装します。

要件

• Python 3.11
• httpx
• httpx-auth
• mcp.server.fastmcp

インストール

1. リポジトリをクローンします：

   git clone https://github.com/chordee/mcp-server-shotgrid.git
   

2. uv をインストールします。 まだインストールしていない場合に必要です。uv は Python 3.11 と pyproject.toml で宣言された依存関係を自動的に管理するため、手動で venv を作成する必要はありません。

3. 認証情報を設定します。 環境変数（推奨）または CLI 引数を使用します。使用方法を参照してください。

4. MCP クライアントにサーバーを登録します。 Claude Code の例（~/.claude.json またはプロジェクトローカルの .mcp.json）：

   {
     "mcpServers": {
       "shotgrid": {
         "command": "uv",
         "args": ["run", "--directory", "D:\\path\\to\\mcp-server-shotgrid", "main.py"],
         "env": {
           "SHOTGRID_HOST": "https://your-shotgrid-url",
           "SHOTGRID_CLIENT_ID": "your_client_id",
           "SHOTGRID_CLIENT_SECRET": "your_client_secret"
         }
       }
     }
   }
   

使用方法

認証情報は、**環境変数（推奨）**または CLI 引数のいずれかで指定できます。環境変数が優先されます。3 つの値のいずれかが両方とも指定されていない場合、サーバーはエラーで終了します。

オプション A — 環境変数（推奨）

変数	説明
SHOTGRID_HOST	ShotGrid のホスト URL。例：https://your-shotgrid-url
SHOTGRID_CLIENT_ID	OAuth2 クライアント ID
SHOTGRID_CLIENT_SECRET	OAuth2 クライアントシークレット

Windows（PowerShell）：

$env:SHOTGRID_HOST = "https://your-shotgrid-url"
$env:SHOTGRID_CLIENT_ID = "your_client_id"
$env:SHOTGRID_CLIENT_SECRET = "your_client_secret"
uv run --directory C:\path\to\mcp-server-shotgrid main.py

macOS / Linux（bash / zsh）：

export SHOTGRID_HOST="https://your-shotgrid-url"
export SHOTGRID_CLIENT_ID="your_client_id"
export SHOTGRID_CLIENT_SECRET="your_client_secret"
uv run --directory /path/to/mcp-server-shotgrid main.py

オプション B — CLI 引数

uv run --directory {REPO_DIR} main.py --host https://your-shotgrid-url --client-id your_client_id --client-secret your_client_secret

短縮形（-host、-ci、-cs）と長形式（--host、--client-id、--client-secret）の両方を使用できます。

セキュリティに関する注意

CLI 引数よりも環境変数の使用を推奨します。コマンドラインで渡した引数は、プロセス一覧（ps、タスク マネージャー）、シェルの履歴、多くのスーパーバイザーや IDE の設定ファイルから確認できるためです。環境変数を使うと誤って情報を公開するリスクを減らせますが、これらも秘密情報です。保護された設定ファイル（例：.mcp.json／~/.claude.json）に保存し、厳格なファイル権限を設定してください。また、秘密情報をバージョン管理にコミットしないでください。

このサーバーは FastMCP を使用し、transport="stdio" のみで通信します。MCP が公開するツールは、LLM エージェントから呼び出せます。

利用可能なツール

すべてのツールは非同期で、FastMCP を介して公開されます。構造化された Python オブジェクト（List または Dict）を返し、MCP フレームワークによって自動的にシリアル化されます。括弧内の引数は、オプションと明記されていない限り必須です。

• get_all_projects(): すべてのプロジェクトを一覧表示します。
• get_all_users(): すべてのユーザーを一覧表示します。
• get_all_projects_field_contains(value: str, field: str = "name"): 指定したフィールドに値を含むプロジェクトを一覧表示します。
• get_sequences(project_id: int (optional), project_name: str (optional), code: str (optional), updated_in_last_n_days: int (optional), updated_date_from: [YYYY,MM,DD] (optional), updated_date_to: [YYYY,MM,DD] (optional)): プロジェクト、コード、日付で任意に絞り込んでシーケンスを一覧表示します。
• get_shots(project_id: int (optional), project_name: str (optional), sequence_id: int (optional), sequence_code: str (optional), shot_code: str (optional), updated_in_last_n_days: int (optional), updated_date_from: [YYYY,MM,DD] (optional), updated_date_to: [YYYY,MM,DD] (optional)): 多数の条件で絞り込んでショットを一覧表示します。
• get_assets(project_id: int (optional), project_name: str (optional), code: str (optional), updated_in_last_n_days: int (optional), updated_date_from: [YYYY,MM,DD] (optional), updated_date_to: [YYYY,MM,DD] (optional)): 任意の条件で絞り込んでアセットを一覧表示します。
• get_tasks(entity_type: str (optional), entity_id: int (optional), project_id: int (optional), project_name: str (optional), user_id: int (optional), task_name: str (optional), updated_in_last_n_days: int (optional), updated_date_from: [YYYY,MM,DD] (optional), updated_date_to: [YYYY,MM,DD] (optional)): 任意の条件で絞り込んでタスクを一覧表示します。
• get_users_name_or_login_contains(name: str (optional), login: str (optional)): 名前またはログイン名に部分文字列を含むユーザーを一覧表示します。
• get_notes(shot_id: int (optional), asset_id: int (optional), user_id: int (optional), task_id: int (optional), version_id: int (optional), project_id: int (optional), project_name: str (optional), task_name: str (optional), asset_code: str (optional), version_name: str (optional), updated_in_last_n_days: int (optional), updated_date_from: [YYYY,MM,DD] (optional), updated_date_to: [YYYY,MM,DD] (optional), limit: int (optional), page: int (optional)): 詳細な絞り込みオプションを使ってノートを一覧表示します。limit / page によるページネーションに対応しているため、大規模なプロジェクトでも ShotGrid のデフォルトページサイズによって結果が暗黙的に切り捨てられることはありません。
• create_note(content: str, project_id: int, subject: str (optional), link_shot_ids: [int] (optional), link_asset_ids: [int] (optional), link_task_ids: [int] (optional), link_version_ids: [int] (optional), task_ids: [int] (optional), addressing_to_user_ids: [int] (optional), addressing_cc_user_ids: [int] (optional), user_id: int (optional), sg_status_list: str (optional)): 新しいノートを作成します。note_links は4つの link_* リストから構成されます。省略した場合、user_id は API ユーザーがデフォルトになります。
• update_note(note_id: int, content: str (optional), subject: str (optional), sg_status_list: str (optional), link_shot_ids: [int] (optional), link_asset_ids: [int] (optional), link_task_ids: [int] (optional), link_version_ids: [int] (optional), task_ids: [int] (optional), addressing_to_user_ids: [int] (optional), addressing_cc_user_ids: [int] (optional)): 既存のノートを更新します。複数エンティティを対象とするリストパラメーターは、指定すると既存の値を置き換えます（クリアするには [] を渡します）。更新では project と user を変更できません。
• delete_note(note_id: int): ID を指定してノートを削除します。
• get_replies(note_id: int, limit: int (optional), page: int (optional)): ノートへの返信を一覧表示し、返信の全フィールド（content、user、entity、タイムスタンプ、attachments）を返します。limit / page によるページネーションに対応しています。ID のみを返していた従来の get_all_replies_with_note_id に代わるものです。
• create_reply(content: str, note_id: int, user_id: int (optional)): ノートへの返信を投稿します。user_id は省略すると API ユーザーがデフォルトになります。
• update_reply(reply_id: int, content: str): 返信の内容を更新します。
• delete_reply(reply_id: int): ID を指定して返信を削除します。
• get_note_attachments(note_id: int): ノートに添付された参照を一覧表示します（軽量な [{id, type, name}]）。
• get_attachment_info(attachment_id: int): 添付ファイルの全メタデータ（this_file の URL、image のサムネイル、表示名、コンテンツタイプ、サイズ）を取得します。
• get_versions(project_id: int (optional), project_name: str (optional), task_id: int (optional), task_name: str (optional), user_id: int (optional), updated_in_last_n_days: int (optional), updated_date_from: [YYYY,MM,DD] (optional), updated_date_to: [YYYY,MM,DD] (optional)): 任意の条件で絞り込んでバージョンを一覧表示します。
• get_bookings(user_ids: [int] (optional), project_ids: [int] (optional), range_from: [YYYY,MM,DD] (optional), range_to: [YYYY,MM,DD] (optional), vacation: bool (optional), exclude_vacation: bool (optional), sg_status_list: "cfrm"|"pndng" (optional), sort_field: "start_date"|"end_date"|"updated_at" (default "start_date"), sort_order: "asc"|"desc" (default "asc"), limit: int (optional), page: int (optional)): 日付の範囲が [range_from, range_to] と重複する予約を一覧表示します。in 関係を使った複数ユーザー・複数プロジェクトのクエリに対応しています。v0.2.0 の破壊的変更：user_id / project_id はリスト形式の user_ids / project_ids に置き換えられ、4つの start_date_from/to / end_date_from/to パラメーターは、重複を両端を含めて判定する range_from / range_to に置き換えられました。
• create_booking(user_id: int, project_id: int, start_date: [YYYY,MM,DD], end_date: [YYYY,MM,DD], vacation: bool (optional), note: str (optional), percent_allocation: float (optional), sg_status_list: "cfrm"|"pndng" (optional)): 新しい予約を作成します。
• update_booking(booking_id: int, start_date: [YYYY,MM,DD] (optional), end_date: [YYYY,MM,DD] (optional), vacation: bool (optional), note: str (optional), percent_allocation: float (optional), sg_status_list: "cfrm"|"pndng" (optional)): 既存の予約を更新します。注：更新では user と project を変更できません。変更する必要がある場合は、予約を削除して作成し直してください。
• delete_booking(booking_id: int): ID を指定して予約を削除します。
• get_entities_updated_in_last_n_days(entity_type: str, n: int, project_id: int (optional)): 過去 n 日以内に更新された、指定したタイプのエンティティを一覧表示します。
• get_entity_by_id(entity_type: str, entity_id: int): タイプと ID を指定してエンティティの詳細を取得します。

エラー処理

サーバーには堅牢なエラー処理ラッパーが含まれており、ShotGrid API のエラーと内部例外を捕捉して、error フィールドと message フィールドを含む構造化された JSON オブジェクトとして返します。

注意事項

• ShotGrid アカウントで API アクセスが有効になっていることを確認してください。
• サーバーは OAuth2 を使用して認証します。
• サーバーは FastMCP を使用して実装されており、transport="stdio" のみで実行されます。
• 認証情報は環境変数（SHOTGRID_HOST、SHOTGRID_CLIENT_ID、SHOTGRID_CLIENT_SECRET）または CLI 引数（-host / --host、-ci / --client-id、-cs / --client-secret）で指定できます。環境変数が優先されます。
• 一部のツールは動的なフィールド取得を使用し、特定のキーを除外します（main.py の remove_exclude_fields を参照）。
• ワークフローに合わせて、必要に応じて main.py のツールを拡張またはカスタマイズしてください。
• ShotGrid REST API のロジックは shotgrid_rest.py に実装されています。

ライセンス

MIT License