MCP Server for Autodesk ShotGrid REST API

MCP Server for Autodesk ShotGrid REST API

This project provides an MCP (Model Context Protocol) server, implemented using FastMCP, that enables Large Language Model (LLM) agents to interact programmatically with Autodesk ShotGrid via its REST API. It exposes a set of tools for querying and managing ShotGrid entities such as projects, assets, tasks, users, notes, and more. The server supports transport="stdio" mode for integration with LLM-based workflows.

Features

• Connects to Autodesk ShotGrid using OAuth2 authentication.
• Exposes ShotGrid REST API operations as MCP tools using FastMCP.
• Query projects, users, assets, tasks, notes, versions, bookings, and more.
• Retrieve detailed information about entities.
• Designed for integration with LLM-based workflows.
• Modular codebase: main.py provides the MCP server and core tool definitions; booking_tools.py handles all Booking CRUD operations; note_tools.py handles Note / Reply CRUD plus attachment reads; shotgrid_rest.py implements the ShotGrid API wrapper.

Requirements

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

Installation

1. Clone the repository:

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

2. Install uv if you don't have it. uv manages Python 3.11 and the dependencies declared in pyproject.toml automatically; no manual venv step is needed.

3. Configure credentials. Use environment variables (recommended) or CLI arguments. See Usage.

4. Register the server with your MCP client. Example for Claude Code (~/.claude.json or a project-local .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"
         }
       }
     }
   }
   

Usage

Credentials can come from either environment variables (recommended) or CLI arguments. Environment variables take precedence; if both are missing for any of the three values, the server exits with an error.

Option A — Environment variables (recommended)

Variable	Description
SHOTGRID_HOST	ShotGrid host URL, e.g. https://your-shotgrid-url
SHOTGRID_CLIENT_ID	OAuth2 client ID
SHOTGRID_CLIENT_SECRET	OAuth2 client secret

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

Option B — CLI arguments

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

Both short (-host, -ci, -cs) and long (--host, --client-id, --client-secret) forms are supported.

Security note

Prefer environment variables over CLI arguments. Arguments passed on the command line are visible in process listings (ps, Task Manager), shell history, and many supervisor/IDE configuration files. Environment variables can reduce accidental exposure, but they are still secrets — store them in protected config files (for example, .mcp.json / ~/.claude.json), use strict file permissions, and never commit secrets to version control.

The server uses FastMCP and communicates via transport="stdio" only. Tools exposed by MCP are available for LLM agents to call.

Available Tools

All tools are asynchronous and exposed via FastMCP. They return structured Python objects (List or Dict) which are automatically serialized by the MCP framework. Arguments in parentheses are required unless marked optional.

• get_all_projects(): List all projects.
• get_all_users(): List all users.
• get_all_projects_field_contains(value: str, field: str = "name"): List projects where a field contains a value.
• 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)): List sequences, optionally filtered by project, code, or date.
• 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)): List shots, with extensive filters.
• 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)): List assets, with optional filters.
• 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)): List tasks, with optional filters.
• get_users_name_or_login_contains(name: str (optional), login: str (optional)): List users whose name or login contains a substring.
• 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)): List notes with comprehensive filtering options. Supports pagination via limit / page so large projects aren't silently truncated to ShotGrid's default page.
• 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)): Create a new Note. note_links is built from the four link_* lists. user_id defaults to the API user when omitted.
• 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)): Update an existing Note. Multi-entity list parameters REPLACE existing values when supplied (pass [] to clear). project and user cannot be changed via update.
• delete_note(note_id: int): Delete a Note by ID.
• get_replies(note_id: int, limit: int (optional), page: int (optional)): List replies under a Note, returning full reply fields (content, user, entity, timestamps, attachments). Supports pagination via limit / page. Replaces the previous get_all_replies_with_note_id, which only returned ids.
• create_reply(content: str, note_id: int, user_id: int (optional)): Post a Reply under a Note. user_id defaults to the API user.
• update_reply(reply_id: int, content: str): Update a Reply's content.
• delete_reply(reply_id: int): Delete a Reply by ID.
• get_note_attachments(note_id: int): List attachment references on a Note (lightweight [{id, type, name}]).
• get_attachment_info(attachment_id: int): Fetch full Attachment metadata (this_file URL, image thumbnail, display name, content type, size).
• 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)): List versions with optional filters.
• 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)): List bookings whose date interval overlaps [range_from, range_to]. Supports multi-user and multi-project queries via the in relation. Breaking change in v0.2.0: user_id/project_id replaced by list-valued user_ids/project_ids; the four start_date_from/to / end_date_from/to parameters were replaced by range_from/range_to with inclusive overlap semantics.
• 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)): Create a new booking.
• 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)): Update an existing booking. Note: user and project cannot be changed via update — delete and recreate the booking if these need to change.
• delete_booking(booking_id: int): Delete a booking by ID.
• get_entities_updated_in_last_n_days(entity_type: str, n: int, project_id: int (optional)): List entities of a type updated in the last n days.
• get_entity_by_id(entity_type: str, entity_id: int): Get details for an entity by type and ID.

Error Handling

The server includes a robust error handling wrapper that captures ShotGrid API errors and internal exceptions, returning them as structured JSON objects with error and message fields.

Notes

• Ensure your ShotGrid account has API access enabled.
• The server uses OAuth2 for authentication.
• The server is implemented using FastMCP and runs with transport="stdio" only.
• Credentials can be provided via environment variables (SHOTGRID_HOST, SHOTGRID_CLIENT_ID, SHOTGRID_CLIENT_SECRET) or CLI arguments (-host / --host, -ci / --client-id, -cs / --client-secret). Env vars take precedence.
• Some tools use dynamic field fetching and exclude certain keys (see remove_exclude_fields in main.py).
• Extend or customize the tools in main.py as needed for your workflow.
• The ShotGrid REST API logic is implemented in shotgrid_rest.py.

License

MIT License