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
• 📊 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

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

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:

• ShotGrid
• Model Context Protocol
• Original Project