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

Get Started

Server

Clients

AI Integration

Development

Patterns

Configuration Examples

ShotGrid MCP Server Configuration Examples

MCP Client Configuration

Claude Desktop / Anthropic Claude

Cursor

Windsurf (Codeium)

Cline (VS Code Extension)

Visual Studio Code

VS Code User Settings

Environment Variables Configuration

Python Configuration

Docker Compose Configuration

Configuration with Multiple Servers

Configuration with Custom Tools

Configuration with Authentication

Integration with FastMCP

MCP Configuration Reference

Server Configuration Reference

Next Steps

Get Started

Server

Clients

AI Integration

Development

Patterns

​ShotGrid MCP Server Configuration Examples

​MCP Client Configuration

​Claude Desktop / Anthropic Claude

​Cursor

​Windsurf (Codeium)

​Cline (VS Code Extension)

​Visual Studio Code

​VS Code User Settings

​Environment Variables Configuration

​Python Configuration

​Docker Compose Configuration

​Configuration with Multiple Servers

​Configuration with Custom Tools

​Configuration with Authentication

​Integration with FastMCP

​MCP Configuration Reference

​Server Configuration Reference

​Next Steps

ShotGrid MCP Server Configuration Examples

MCP Client Configuration

Claude Desktop / Anthropic Claude

Cursor

Windsurf (Codeium)

Cline (VS Code Extension)

Visual Studio Code

VS Code User Settings

Environment Variables Configuration

Python Configuration

Docker Compose Configuration

Configuration with Multiple Servers

Configuration with Custom Tools

Configuration with Authentication

Integration with FastMCP

MCP Configuration Reference

Server Configuration Reference

Next Steps