ShotGrid MCP server (lean)

A Model Context Protocol server that gives LLM agents (Claude Desktop, Claude Code, Cursor, …) full access to the ShotGrid / Autodesk Flow Production Tracking API through a small, curated, agent-first tool surface. A leaner, write-safe repackaging of loonghao/shotgrid-mcp-server (credit below).

ShotGrid is schema-driven, so a handful of generic CRUD + query tools reach every entity type. This server leans into that: 16 tools, one CRUD family, a dry_run safety gate on every write.

Built on the shoulders of loonghao/shotgrid-mcp-server

This project owes a real debt to loonghao/shotgrid-mcp-server (MIT) — the first solid, well-engineered ShotGrid MCP. We used it heavily and it works: connection pooling, a schema cache, an error_handler, and mockgun-based tests are all things it gets right, and it proved the concept. Go star it. This server isn't a replacement so much as a leaner, hardened repackaging of the same idea, tuned specifically for autonomous agents — where a tighter, safer tool surface matters more than breadth.

What we changed to make it more solid

Three changes, each aimed at making an agent's life safer and more predictable:

Net: same 100% reach (both are generic over ShotGrid's schema), a fraction of the tool count, and safe-by-default writes. Where the original optimizes for human convenience and breadth, this one optimizes for an agent that needs to choose correctly and not break things.

Related MCP server: MCP-NG

The 16 tools

Generic power tools (full reach over every entity type):

• find · find_one — query with ShotGrid filters + field projections

• create · update · delete · revive — single-entity writes (delete = reversible retire)

• batch — atomic multi-op create/update/delete

Schema & discovery (so the agent can learn the site first):

• schema_entity_read — all entity types

• schema_field_read — fields + types for one entity type

• summarize — server-side aggregation / status roll-ups (no rows pulled)

• text_search — global text search across entity types

High-value helpers (not just a canned filter):

• whoami — connection + server info

• find_projects — common entry point

• project_summary — a normalized project snapshot (counts + per-shot cast/status/thumbnail, canonical statuses) for cross-tracker verify/diff

• download_thumbnail — pull an entity's thumbnail/filmstrip to disk

• upload — attach a file / set a thumbnail / fill a media field

Every write tool takes dry_run (default false). create / update / delete support two preview levels: dry_run="plan" (client-side echo, no server contact) and dry_run="preflight" — a real dry run that resolves every referenced entity against live data, validates sg_status_list values against the live schema, returns a before→after diff for updates, and a verdict of ok/would_fail — without writing. Set MCP_PLAN_LOG=/path.jsonl to capture each plan/preflight as a reviewable plan file. (Other write tools take dry_run as a plain boolean.)

Install

pip install -r requirements.txt        # fastmcp, shotgun_api3, requests

Configure (credentials)

Create a Script in ShotGrid (Admin ▸ Scripts ▸ + Add Script) and set three env vars (or pass them in your MCP client config):

For local dev you can instead drop them in a .env next to server.py (gitignored — see .env.example).

Run / wire into a client

python3 server.py        # stdio transport

Claude Code:

claude mcp add shotgrid -- python3 /path/to/shotgrid-mcp/server.py

Claude Desktop / Cursor (mcpServers entry):

{
  "mcpServers": {
    "shotgrid": {
      "command": "python3",
      "args": ["/path/to/shotgrid-mcp/server.py"],
      "env": {
        "SHOTGRID_URL": "https://yourstudio.shotgrid.autodesk.com",
        "SHOTGRID_SCRIPT_NAME": "mcp",
        "SHOTGRID_API_KEY": "••••"
      }
    }
  }
}

Examples (what the agent calls)

# every shot In Progress on a project, with assignees
find("Shot",
     [["project","is",{"type":"Project","id":85}], ["sg_status_list","is","ip"]],
     ["code","sg_status_list","task_template"])

# status roll-up without pulling rows
summarize("Task", [["project","is",{"type":"Project","id":85}]],
          [{"field":"id","type":"count"}],
          grouping=[{"field":"sg_status_list","type":"exact","direction":"asc"}])

# preview a write before committing
create("Shot", {"project":{"type":"Project","id":85}, "code":"sh010"}, dry_run=True)

Part of a tracker-MCP quintet — migrate projects between platforms

This is one of five sibling tracker MCPs, each with the same shape (generic CRUD + schema + typed convenience, with a dry_run gate): shotgrid-mcp (this repo), ftrack-mcp, and kitsu-mcp, and ayon-mcp, and nim-mcp. They all speak the same production model (Project → Sequence/Asset → Shot → Task → Version/Status), so an agent with two of them loaded can migrate a project from one tracker to another — read the structure from the source MCP, recreate it via the target's create/new_* tools, no bespoke migration script. This trio grew out of copying one project across all three platforms.

📊 See COMPARISON.md for a side-by-side of the four trackers (data model, status vocabularies) and the migration incompatibilities to know about (e.g. casting can't round-trip through ftrack; statuses must be mapped; media/notes/custom fields don't carry yet).

🧪 See TESTING.md for how these servers are validated — live round-trip tests, two-level dry-run checks, and the cross-tracker migration matrix (including what is not yet covered, stated plainly).

Credits

• loonghao/shotgrid-mcp-server (MIT) — the original ShotGrid MCP this builds on. The design and much of the API ergonomics here are downstream of that work; please credit and star it.

• Autodesk's shotgun_api3 — the underlying Python API.

• Companion to our ftrack-mcp.

MIT licensed. If the extra breadth of the original suits you better, use it — this is just the leaner, agent-hardened cut.

Built by John Huikku · alienrobot.com