Shotgrid MCP Rs

🚀 shotgrid-mcp-rs

A modern Rust implementation of the ShotGrid/Flow Production Tracking REST API client with native MCP server support, enabling Large Language Models to interact with ShotGrid directly.

⚠️ Important Note

This is a test/experimental project and should NEVER be used in production environments. The software is provided "AS IS" without warranty of any kind, express or implied. The author assumes NO RESPONSIBILITY for any damages, data loss, or issues arising from the use of this software. Use at your own risk.

Author: Alex Khalyavin joss13@gmail.com

Based on: LaikaStudios/shotgrid-rs by Owen Nelson, Alex Widener, and Marina Wilding at LAIKA Studios

This fork extends their excellent foundation with MCP server implementation and modern tooling. Special thanks to the original authors for their pioneering work on Rust ShotGrid integration.

🚀 Quick Start

As a Rust Library

Add to your Cargo.toml:

[dependencies]
shotgrid-mcp-rs = { version = "0.9", features = ["mcp"] }

See README.dev.md for detailed code examples and API documentation.

As an MCP Server (Recommended)

Enable LLMs to interact with your ShotGrid instance via the Model Context Protocol.

Installation

Option 1: Install from crates.io

cargo install shotgrid-mcp-rs --all-features

Option 2: Install from source

# Clone the repository
git clone https://github.com/ssoj13/shotgrid-mcp-rs
cd shotgrid-mcp-rs

# Set up environment variables (required for ORM code generation)
export SG_SERVER="https://yoursite.shotgrid.autodesk.com"
export SG_SCRIPT_NAME="your_script_name"
export SG_SCRIPT_KEY="your_script_key"

# Generate ORM models and install
./bootstrap.ps1 codegen
cargo install --path . --all-features

After installation, the shotgrid-mcp-rs binary will be available globally in ~/.cargo/bin/.

Option 3: Build only (without installing)

cargo build --release --bin shotgrid-mcp-rs --features=mcp

Binary location:

• Windows: target/release/shotgrid-mcp-rs.exe
• Linux/macOS: target/release/shotgrid-mcp-rs

CLI Options

shotgrid-mcp-rs [OPTIONS]

Options:
  --url <URL>                ShotGrid server URL (overrides SG_SERVER env var)
  --script-name <NAME>       Script name (overrides SG_SCRIPT_NAME env var)
  --script-key <KEY>         Script key (overrides SG_SCRIPT_KEY env var)
  -s, --stream              Enable HTTP stream mode (default: stdio)
  -p, --port <PORT>         HTTP port for stream mode [default: 8000]
  -b, --bind <ADDRESS>      Bind address for stream mode [default: 127.0.0.1]
  --log [<FILE>]            Enable file logging [default: shotgrid-mcp-rs.log]
  -h, --help                Print help
  -V, --version             Print version

Usage Examples

stdio mode (default):

# Using environment variables
export SG_SERVER="https://yoursite.shotgrid.autodesk.com"
export SG_SCRIPT_NAME="your_script_name"
export SG_SCRIPT_KEY="your_script_key"
shotgrid-mcp-rs

# Using CLI arguments
shotgrid-mcp-rs \
  --url https://yoursite.shotgrid.autodesk.com \
  --script-name your_script_name \
  --script-key your_script_key

# With file logging
shotgrid-mcp-rs --log my-server.log

HTTP stream mode:

# Default port 8000
shotgrid-mcp-rs -s

# Custom port and bind address
shotgrid-mcp-rs -s -p 3000 -b 0.0.0.0

# With logging
shotgrid-mcp-rs -s --log

# Test the server
curl http://127.0.0.1:8000/health  # Should return "OK"

Configure Claude Desktop

Add to your Claude Desktop configuration (claude_desktop_config.json):

Location:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "shotgrid": {
      "command": "shotgrid-mcp-rs",
      "env": {
        "SG_SERVER": "https://yoursite.shotgrid.autodesk.com",
        "SG_SCRIPT_NAME": "your_script_name",
        "SG_SCRIPT_KEY": "your_script_key"
      }
    }
  }
}

Windows (with absolute path):

{
  "mcpServers": {
    "shotgrid": {
      "command": "C:\\Users\\YourName\\.cargo\\bin\\shotgrid-mcp-rs.exe",
      "env": {
        "SG_SERVER": "https://yoursite.shotgrid.autodesk.com",
        "SG_SCRIPT_NAME": "your_script_name",
        "SG_SCRIPT_KEY": "your_script_key"
      }
    }
  }
}

Configure Claude Code / Codex

Add to your Claude Code MCP settings:

{
  "mcpServers": {
    "shotgrid": {
      "command": "shotgrid-mcp-rs",
      "env": {
        "SG_SERVER": "https://yoursite.shotgrid.autodesk.com",
        "SG_SCRIPT_NAME": "your_script_name",
        "SG_SCRIPT_KEY": "your_script_key"
      }
    }
  }
}

MCP Tools Available (14 tools)

Basic CRUD (8 tools)

• schema_read - Get entity field schemas
• search_entities - Search with filters/pagination
• find_one - Find single entity
• read_entity - Read by ID
• create_entity - Create new entity
• update_entity - Update existing
• delete_entity - Soft delete
• revive_entity - Restore deleted

TimeLog Management (2 tools)

• read_timelogs - Query time entries
• timelog_stats - Aggregate statistics

Advanced Operations (4 tools)

• text_search - Cross-entity search
• summarize - SQL-like aggregation
• batch - Bulk operations
• note_thread_read - Full conversation threads

✨ Features

MCP (Model Context Protocol)

The mcp feature enables the MCP server with all 14 tools. This is the primary use case for this fork.

shotgrid-mcp-rs = { version = "0.9", features = ["mcp"] }

ORM Layer

The orm feature provides type-safe entity models with code generation from your ShotGrid schema.

shotgrid-mcp-rs = { version = "0.9", features = ["orm"] }

Generate models:

# Set environment variables
export SG_SERVER=https://yoursite.shotgrid.autodesk.com
export SG_SCRIPT_NAME=your_script_name
export SG_SCRIPT_KEY=your_script_key

# Generate models from schema
cargo xtask codegen

See README.dev.md for ORM usage examples.

📚 Documentation

• Monument2_Production_Report_5Days.md - Example report created by LLM from a single prompt
• README.dev.md - Complete API documentation, code examples, and development guide
• README.mcp.md - MCP server documentation
• README.codegen.md - ORM code generation documentation
• CHANGELOG.md - Version history and changes

🔧 Technical Details

Transport Modes

The MCP server supports two transport modes:

1. stdio (Default) - Local Mode

• Use for: Claude Desktop, Claude Code, Codex, and other local MCP clients
• Protocol: JSON-RPC over stdin/stdout
• Logging: Silent by default (stderr logging breaks MCP handshake)
• File logging: Available with --log flag

2. HTTP Stream - Remote/Web Mode

• Use for: Web clients, remote access, debugging, development
• Protocol: Server-Sent Events (SSE) over HTTP
• Endpoints:
  • /mcp - MCP protocol endpoint
  • /health - Health check (returns "OK")
• Logging: Console + optional file logging
• Session management: Built-in session handling

Switching modes: Use -s/--stream flag to enable HTTP mode.

Input Validation & Sanitization

The MCP server includes automatic input sanitization to prevent common errors caused by whitespace in field names and filter parameters. This feature was added to handle inconsistencies from different MCP clients (Claude Code, Codex, etc.).

What Gets Sanitized

Field Names in Filters:

// Before sanitization (causes API errors)
[" sg_status_list", "is", "ip"]

// After sanitization (works correctly)
["sg_status_list", "is", "ip"]

Object Keys:

// Before
{" project": {"type": "Project", "id": 123}}

// After
{"project": {"type": "Project", "id": 123}}

Field Lists:

// Before
["id", " name ", " sg_status_list "]

// After
["id", "name", "sg_status_list"]

Where It's Applied

Sanitization is automatically applied to:

• search_entities / find_one - filters and fields parameters
• create_entity / update_entity - Object keys in data parameter and return_fields
• read_entity - fields parameter
• summarize - filters and summary_fields parameters
• text_search - entity_filters parameter
• batch - All request parameters
• read_timelogs - fields parameter

Benefits

• ✅ Prevents API errors - No more "field doesn't exist" errors due to whitespace
• ✅ Transparent - Works automatically, no code changes needed
• ✅ Logged - Debug logging shows when sanitization occurs
• ✅ Comprehensive - Handles nested structures and complex filters

Example Error Prevention

Before sanitization:

Error: API read() Task. sg_status_list doesn't exist.
Value: {" sg_status_list": " does not exist..."}

After sanitization:

Success: Field names automatically trimmed, query executes correctly

Testing

# Unit tests
cargo test

# HTTP transport tests
cargo test --test http_transport

# Integration tests (requires live ShotGrid server)
cargo test --features integration-tests

# MCP-specific tests
cargo test --lib mcp::tests

# All tests
cargo test --all

HTTP Transport Tests: The tests/http_transport.rs module contains tests for the HTTP stream mode:

• Server health check endpoint
• MCP endpoint accessibility
• Custom port and bind address
• File logging functionality

Note: HTTP tests spawn a real server process, so they require:

• ShotGrid credentials in environment variables
• Available network ports (automatically finds free ports)
• Takes ~10 seconds due to server startup time

Required environment variables for integration tests:

• TEST_SG_SERVER - ShotGrid server URL
• TEST_SG_SCRIPT_NAME - API user name
• TEST_SG_SCRIPT_KEY - API key
• TEST_SG_HUMAN_USER_LOGIN - HumanUser login for sudo tests
• TEST_SG_PROJECT_ID - Test project ID

📄 License

Licensed under the MIT License - see the LICENSE file for details.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you shall be licensed under the MIT license, without any additional terms or conditions.

Links:

• ShotGrid
• Model Context Protocol
• Original Project