Shotgrid MCP Server

A Model Context Protocol server for ShotGrid (aka. Flow Production Tracking, Shotgun, Shitgord, Prince).

Gives your LLM accurate, live knowledge of your ShotGrid instance providing schema, entities, filter operators, and embedded API docs, allowing it to write reliable pipeline code without hallucinating field names or entity types.

• Built on ShotgunGo and MiniMcp 100% stdlib go.
• Compiles to a single self-contained binary on linux, mac, and windows.

Security

The server binary is written in 100% stdlib go with no externally owned dependencies, so no supply chain attack risk at runtime.
The one build-time exception is pandoc, used by go generate to convert the published API docs to markdown. It is installed in the Docker builder stage only and is not part of the shipped image or binary.
The build process uses go's vulncheck system to detect any stdlib issues,
This shouldn't however be an issue as you'll be running this in a controlled environment. cant hurt.

Tools

Pass project_id to schema tools to get project-specific field configuration — required for accurate status values, which vary per pipeline.

Exporting large result sets to CSV

sg_find returns every row into the LLM's context. For big pulls, or anything you want to
filter, group or join, use sg_find_csv instead: it pages through the whole result server-side,
writes a CSV, and returns just {path, host_path, rows, columns, truncated}. Load the file with a
SQLite tool (e.g. SQLiteMCP's import_csv with
create=true, sample_rows=-1) and query it with SQL.

• Files are written to the server's export directory (SG_EXPORT_DIR, /exports in the container).
  filename is a bare name only, so the tool cannot write anywhere else. It refuses to overwrite
  unless overwrite=true, and the file only appears once the whole export succeeded.
• max_rows defaults to 100000; truncated: true means more rows matched.
• id is always the first column. Link fields are flattened so the CSV stays flat:

• In Docker the container can't write to your filesystem, so docker-compose.yml bind-mounts
  SG_EXPORT_HOST_DIR at /exports and runs as SG_EXPORT_UID:SG_EXPORT_GID. host_path in the
  result is the path on the host, which is what you pass to the SQLite tool.

Prompt

sg_query_guide is registered as an MCP prompt (clients that support prompts can inject it as conversation context). Clients that don't surface prompts can use sg_initialize instead, which returns the same content as a tool call.

Credentials

Credentials are read from environment variables:

Copy .env.example to .env and fill in your values. The server validates credentials on startup — it will refuse to start if the connection fails.

Running

Docker (recommended)

docker compose up -d

The server listens on http://127.0.0.1:3000.

From source

# Install and run govulncheck (optional, but recommended)
go install golang.org/x/vuln/cmd/govulncheck@latest
govulncheck ./...

# Build the embedded API docs (needs pandoc on PATH and network access; one-time, or to refresh)
go generate ./...

# stdio transport (Claude Code CLI)
go run . 

# HTTP transport (Zed, remote clients)
go run . -http

# Override listen address
go run . -http -addr :8080

Binary Files

pre-build binaries can be found on the Releases page

Connecting

Claude Code CLI

Add to ~/.claude/.mcp.json:

{
  "mcpServers": {
    "shotgrid": {
      "command": "sg-mcp",
      "args": []
    }
  }
}

Zed (SSH remote project)

Zed must connect via URL even when the server is local. When using an SSH remote project, As of time of writing Zed spawns stdio MCP servers on the local machine rather than the remote host — the HTTP transport is required so the server runs where it has network access to ShotGrid.

Run the server on the remote machine, forward the port over SSH:

# ~/.ssh/config
Host your-host
    LocalForward 3000 localhost:3000

Then configure Zed:

{
  "shotgrid": {
    "url": "http://127.0.0.1:3000/mcp"
  }
}

Development

Refreshing embedded docs

The API documentation is embedded in the binary as docs.json, generated (and gitignored) from the published python-api docs. Building it needs network access and pandoc on PATH:

go generate ./...

This runs cmd/fetchdocs, which reads the page list from the site's Sphinx search index, fetches each page's HTML, converts it to markdown with pandoc, splits every page by heading into sections, and writes docs.json. The site is used rather than the repository's .rst files because the API reference there is an unpopulated autodoc stub; the real text lives in Python docstrings that only the built site contains. The generator fails (rather than shipping stubs) if any page fails to fetch or convert, or if the reference page comes out suspiciously small.

docs.json is a flat map of sections keyed by path ID. IDs are lowercase slugs joined by /, so a section's parent is its ID minus the last segment, and lookup is a plain key access:

{
  "version": 1,
  "roots": ["advanced", "authentication", "reference", "..."],
  "nodes": {
    "reference/shotgun_methods/crud_methods/find": {
      "title": "Shotgun.find",
      "children": [],
      "body": "`Shotgun.find(entity_type: str, ...)`\n\nFind entities matching the given filters...",
      "chars": 4792,
      "subtree_chars": 4792
    }
  }
}

children is in document order (the IDs alone can't express that). body is the section's own text only, so nothing is stored twice; chars / subtree_chars let sg_docs_topics show what fetching a section will cost before the LLM commits to it. Autodoc signature headings become the bare name (find) with the full signature as the first line of the body, and class members nest under their class (reference/exceptions/shotgunerror/add_note).

govulncheck only flags vulnerabilities in code paths that are actually reachable — not every CVE in the dependency tree. Known vulnerabilities are tracked at pkg.go.dev/vuln. If you are deploying this in a production environment, running govulncheck before each build is recommended.

Query guidance

Edit prompts/query_guide.md to update the guidance returned by sg_initialize and the sg_query_guide prompt. A rebuild is required to pick up changes since the file is embedded at compile time.

sg_initialize is named so that LLMs infer that its needed to connect to ShotGrid. This means they tend to call it before making any other API requests which is handy, but you can also tell them to call it if they fail to.