Configuration Examples

Different ways to configure ShotGrid MCP Server

ShotGrid MCP Server Configuration Examples

This page provides various examples of how to configure ShotGrid MCP Server for different environments and use cases. These configuration examples demonstrate how to integrate the server into your pipeline.

MCP Client Configuration

ShotGrid MCP Server follows the standard MCP configuration format. Since it’s a Python-based service, it uses uvx as the command to launch the server. Below are configuration examples for various AI tools and IDEs.

Claude Desktop / Anthropic Claude

{
  "mcpServers": {
    "shotgrid-server": {
      "command": "uvx",
      "args": [
        "shotgrid-mcp-server"
      ],
      "env": {
        "SHOTGRID_SCRIPT_NAME": "XXX",
        "SHOTGRID_SCRIPT_KEY": "XX",
        "SHOTGRID_URL": "XXXX"
      },
      "disabled": false,
      "alwaysAllow": [
        "search_entities",
        "create_entity",
        "batch_create",
        "find_entity",
        "get_entity_types",
        "update_entity",
        "download_thumbnail",
        "batch_update",
        "delete_entity",
        "batch_delete"
      ]
    }
  }
}

Cursor

// .cursor/mcp.json
{
  "mcpServers": {
    "shotgrid-server": {
      "command": "uvx",
      "args": [
        "shotgrid-mcp-server"
      ],
      "env": {
        "SHOTGRID_SCRIPT_NAME": "XXX",
        "SHOTGRID_SCRIPT_KEY": "XX",
        "SHOTGRID_URL": "XXXX"
      }
    }
  }
}

Windsurf (Codeium)

// MCP configuration
{
  "mcpServers": {
    "shotgrid-server": {
      "command": "uvx",
      "args": [
        "shotgrid-mcp-server"
      ],
      "env": {
        "SHOTGRID_SCRIPT_NAME": "XXX",
        "SHOTGRID_SCRIPT_KEY": "XX",
        "SHOTGRID_URL": "XXXX"
      }
    }
  }
}

Cline (VS Code Extension)

// MCP configuration
{
  "mcpServers": {
    "shotgrid-server": {
      "command": "uvx",
      "args": [
        "shotgrid-mcp-server"
      ],
      "env": {
        "SHOTGRID_SCRIPT_NAME": "XXX",
        "SHOTGRID_SCRIPT_KEY": "XX",
        "SHOTGRID_URL": "XXXX"
      }
    }
  }
}

Visual Studio Code

// .vscode/mcp.json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "shotgrid-script-name",
      "description": "ShotGrid Script Name",
      "password": false
    },
    {
      "type": "promptString",
      "id": "shotgrid-script-key",
      "description": "ShotGrid Script Key",
      "password": true
    },
    {
      "type": "promptString",
      "id": "shotgrid-url",
      "description": "ShotGrid URL",
      "password": false
    }
  ],
  "servers": {
    "shotgrid-server": {
      "type": "stdio",
      "command": "uvx",
      "args": ["shotgrid-mcp-server"],
      "env": {
        "SHOTGRID_SCRIPT_NAME": "${input:shotgrid-script-name}",
        "SHOTGRID_SCRIPT_KEY": "${input:shotgrid-script-key}",
        "SHOTGRID_URL": "${input:shotgrid-url}"
      }
    }
  }
}

VS Code User Settings

// settings.json
{
  "mcp": {
    "shotgrid-server": {
      "type": "stdio",
      "command": "uvx",
      "args": ["shotgrid-mcp-server"],
      "env": {
        "SHOTGRID_SCRIPT_NAME": "XXX",
        "SHOTGRID_SCRIPT_KEY": "XX",
        "SHOTGRID_URL": "XXXX"
      }
    }
  },
  "chat.mcp.discovery.enabled": true
}

These configurations tell the MCP client how to launch and connect to the ShotGrid MCP Server. The server will be available to AI assistants as a tool provider.

Environment Variables Configuration

For production deployments, you can use environment variables to configure the server:

# ShotGrid credentials (required)
export SHOTGRID_URL="https://your-studio.shotgunstudio.com"
export SHOTGRID_SCRIPT_NAME="your_script_name"
export SHOTGRID_SCRIPT_KEY="your_script_key"

# Optional settings
export SHOTGRID_CUSTOM_ENTITY_TYPES="CustomEntity07,CustomEntity08"
export SHOTGUN_HTTP_PROXY="http://proxy.example.com:8080"
export SHOTGUN_API_CACERTS="/path/to/cacerts.pem"

Then you can start the server with:

uvx shotgrid-mcp-server

Python Configuration

When using the server in a Python script, you can configure it programmatically:

import os
from shotgrid_mcp_server.connection_pool import RealShotgunFactory
from shotgrid_mcp_server.server import create_server

# Create a ShotGrid client factory
factory = RealShotgunFactory(
    url="https://your-studio.shotgunstudio.com",
    script_name="your_script_name",
    script_key="your_script_key",
    http_proxy=None,  # Optional HTTP proxy
    ca_certs=None     # Optional CA certificates path
)

# Create server with the factory
server = create_server(factory=factory)

# Define custom tools if needed
@server.tool()
def find_shots(project_name: str, status: str = None):
    """Find shots in a project, optionally filtered by status."""
    # Implementation...

# Run the server
if __name__ == "__main__":
    server.run()

Docker Compose Configuration

For containerized deployments, you can use Docker Compose:

version: '3'

services:
  shotgrid-mcp-server:
    image: shotgrid-mcp-server:latest
    ports:
      - "8000:8000"
    environment:
      - SHOTGRID_URL=https://your-studio.shotgunstudio.com
      - SHOTGRID_SCRIPT_NAME=your_script_name
      - SHOTGRID_SCRIPT_KEY=your_script_key
      - SHOTGRID_CUSTOM_ENTITY_TYPES=CustomEntity07,CustomEntity08
      - SHOTGUN_HTTP_PROXY=http://proxy.example.com:8080
    volumes:
      - ./logs:/app/logs
    restart: unless-stopped

Configuration with Multiple Servers

You can configure multiple ShotGrid MCP Servers for different purposes, such as production and testing environments:

{
  "mcpServers": {
    "shotgrid-production": {
      "command": "uvx",
      "args": [
        "shotgrid-mcp-server"
      ],
      "env": {
        "SHOTGRID_URL": "https://production.shotgunstudio.com",
        "SHOTGRID_SCRIPT_NAME": "production_script",
        "SHOTGRID_SCRIPT_KEY": "production_key"
      }
    },
    "shotgrid-testing": {
      "command": "uvx",
      "args": [
        "shotgrid-mcp-server"
      ],
      "env": {
        "SHOTGRID_URL": "https://testing.shotgunstudio.com",
        "SHOTGRID_SCRIPT_NAME": "testing_script",
        "SHOTGRID_SCRIPT_KEY": "testing_key",
        "SHOTGRID_CUSTOM_ENTITY_TYPES": "CustomEntity07,CustomEntity08"
      }
    }
  }
}

With this configuration, AI assistants can access both production and testing ShotGrid environments through different tool providers.

Configuration with Custom Tools

You can configure the server to load custom tools from a specific module. This is useful when you want to extend the server with your own tools:

{
  "mcpServers": {
    "shotgrid-custom": {
      "command": "uvx",
      "args": [
        "python",
        "-m",
        "your_custom_module"
      ],
      "env": {
        "SHOTGRID_URL": "https://your-studio.shotgunstudio.com",
        "SHOTGRID_SCRIPT_NAME": "your_script_name",
        "SHOTGRID_SCRIPT_KEY": "your_script_key",
        "PYTHONPATH": "/path/to/your/modules"
      }
    }
  }
}

Where your_custom_module.py might look like:

import os
from shotgrid_mcp_server.connection_pool import RealShotgunFactory
from shotgrid_mcp_server.server import create_server
from your_tools import register_tools

# Create a ShotGrid client factory
factory = RealShotgunFactory(
    url=os.environ.get("SHOTGRID_URL"),
    script_name=os.environ.get("SHOTGRID_SCRIPT_NAME"),
    script_key=os.environ.get("SHOTGRID_SCRIPT_KEY")
)

# Create server with the factory
server = create_server(factory=factory)

# Register custom tools
register_tools(server)

# Run the server
if __name__ == "__main__":
    server.run()

This approach allows you to create specialized tools for your studio’s specific workflows.

Configuration with Authentication

For secure deployments, you can configure authentication for the MCP server:

{
  "mcpServers": {
    "shotgrid": {
      "command": "uvx",
      "args": [
        "shotgrid-mcp-server"
      ],
      "env": {
        "SHOTGRID_URL": "https://your-studio.shotgunstudio.com",
        "SHOTGRID_SCRIPT_NAME": "your_script_name",
        "SHOTGRID_SCRIPT_KEY": "your_script_key"
      },
      "auth": {
        "username": "admin",
        "password": "secure_password"
      }
    }
  }
}

This adds an authentication layer to your MCP server, requiring clients to provide credentials when connecting.

Integration with FastMCP

ShotGrid MCP Server is built on FastMCP, so you can use FastMCP features:

import os
from shotgrid_mcp_server.connection_pool import RealShotgunFactory
from shotgrid_mcp_server.server import create_server
from fastmcp.middleware import CORSMiddleware

# Create a ShotGrid client factory
factory = RealShotgunFactory(
    url="https://your-studio.shotgunstudio.com",
    script_name="your_script_name",
    script_key="your_script_key"
)

# Create server with the factory
server = create_server(factory=factory)

# Add CORS middleware
server.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:3000"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"]
)

# Run the server
if __name__ == "__main__":
    server.run()

MCP Configuration Reference

Here’s a reference of the supported configuration options for the ShotGrid MCP Server in the MCP configuration file:

Field	Description
command	Must be "uvx" for Python-based ShotGrid MCP Server
args	Array containing ["shotgrid-mcp-server"] or custom module path
env.SHOTGRID_URL	URL of your ShotGrid instance
env.SHOTGRID_SCRIPT_NAME	Script name for API authentication
env.SHOTGRID_SCRIPT_KEY	API key for authentication
env.SHOTGRID_CUSTOM_ENTITY_TYPES	Optional comma-separated list of custom entity types
env.SHOTGUN_HTTP_PROXY	Optional HTTP proxy for ShotGrid API calls
env.SHOTGUN_API_CACERTS	Optional path to CA certificates file

Server Configuration Reference

Here’s a reference of the supported configuration options when initializing the ShotGrid MCP Server in Python:

Parameter	Environment Variable	Type	Default	Description
name	-	str	”shotgrid-server”	Name of the server
shotgrid_url	SHOTGRID_URL	str	None	URL of your ShotGrid instance
script_name	SHOTGRID_SCRIPT_NAME	str	None	Script name for API authentication
script_key	SHOTGRID_SCRIPT_KEY	str	None	API key for authentication
http_proxy	SHOTGUN_HTTP_PROXY	str	None	HTTP proxy for ShotGrid API calls
ca_certs	SHOTGUN_API_CACERTS	str	None	Path to CA certificates file

Next Steps

Now that you’ve seen examples of how to configure ShotGrid MCP Server, you can:

• Check out the Usage Examples for practical examples of using the server
• Learn about optimized queries for better performance
• Explore batch operations for efficient data manipulation