shotgrid-mcp-rs

⚠️ WARNING: EXPERIMENTAL PROJECT - NOT FOR PRODUCTION USE

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.

What is this?

shotgrid-mcp-rs is a modern Rust implementation of the ShotGrid/Flow Production Tracking REST API client with native MCP (Model Context Protocol) server support, enabling Large Language Models to interact with ShotGrid directly.

This is a complete rewrite and extension of the original LaikaStudios project, adding:

🆕 New Features (This Fork)

🤖 Native MCP Server - 14 comprehensive tools for LLM integration, tested with Anthropic Claude Code and OpenAI Codex
⚡ Modern Async/Await - Full tokio-based async runtime
🔧 Enhanced Error Handling - Comprehensive error types and better diagnostics
🧹 Automatic Input Sanitization - Automatically removes whitespace from field names in filters, preventing common API errors
📊 TimeLog Tools - Dedicated tools for time tracking and statistics
🧪 Extensive Testing - Both unit and integration test coverage
📝 Complete Documentation - Comprehensive API docs and examples
🛠️ Optional ORM Layer - Type-safe entity models with code generation
🔄 Batch Operations - Efficient bulk processing

Core Capabilities

Complete CRUD operations (create, read, update, delete, revive)
Advanced search with complex filters (AND/OR/NOT logic)
Text search across multiple entity types (Google-like)
Batch operations for bulk processing
Summarization and aggregation (GROUP BY, COUNT, SUM, AVG, MIN, MAX)
Note threads with replies and attachments
Schema introspection
TimeLog tracking and statistics
Automatic input validation and sanitization - Removes leading/trailing whitespace from field names, object keys, and filter parameters to prevent ShotGrid API errors

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.

Quick Start

1. 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.

2. 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

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

Project Status

Current Fork (shotgrid-mcp-rs)

Modern Rust 2021 edition
Full shotgrid_api + ORM implementation in Rust
MCP server implementation
Full async/await support
Comprehensive documentation

Original Project (LaikaStudios/shotgrid-rs)

⚠️ Last updated ~5 years ago
⚠️ No longer maintained (?)
⚠️ Original authors: Owen Nelson, Alex Widener, Marina Wilding (LAIKA Studios)

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:

Name		Name	Last commit message	Last commit date
Latest commit History 43 Commits
.cargo		.cargo
.github/workflows		.github/workflows
.grok		.grok
docs		docs
examples		examples
src		src
tests		tests
xtask		xtask
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md
bootstrap.ps1		bootstrap.ps1
bootstrap.sh		bootstrap.sh

License

ssoj13/shotgrid-mcp-rs

Folders and files

Latest commit

History

Repository files navigation

shotgrid-mcp-rs

What is this?

🆕 New Features (This Fork)

Core Capabilities

Transport Modes

1. stdio (Default) - Local Mode

2. HTTP Stream - Remote/Web Mode

Quick Start

1. As a Rust Library

2. As an MCP Server (Recommended)

Installation

CLI Options

Usage Examples

Configure Claude Desktop

Configure Claude Code / Codex

MCP Tools Available (14 tools)

Features

MCP (Model Context Protocol)

ORM Layer

Documentation

Input Validation & Sanitization

What Gets Sanitized

Where It's Applied

Benefits

Example Error Prevention

Testing

Project Status

Current Fork (shotgrid-mcp-rs)

Original Project (LaikaStudios/shotgrid-rs)

License

Contribution

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Contributors 2

Uh oh!

Languages

Packages