ftrack MCP Server

A Model Context Protocol (MCP) server that provides AI assistants (like Claude) with full access to the ftrack production tracking API. This enables natural language interactions with your ftrack workspace - query projects, manage tasks, update statuses, and more.

Prerequisites

• Node.js 18 or higher
• ftrack account with API access
• MCP-compatible client (Claude Desktop, Cursor, VS Code with Claude extension, etc.)

Note: This project was developed and tested on Windows. It should work on macOS and Linux but hasn't been tested on those platforms yet. If you encounter issues, please open an issue on GitHub.

Installation

1. Clone the repository

git clone https://github.com/VFX-Tools-LLC/ftrack-mcp.git
cd ftrack-mcp

2. Install dependencies

npm install

3. Get your ftrack API credentials

1. Log into your ftrack workspace
2. Go to Settings > API Keys (or click your avatar > Settings > API Keys)
3. Create a new API key or use an existing one
4. Note down:

• Your ftrack server URL (e.g., https://your-workspace.ftrackapp.com)
• Your username
• Your API key

Configuration

Step 1: Set Credentials

Option A: `.env` file (easiest for local development)

Copy .env.example to .env and fill in your credentials:

cp .env.example .env

FTRACK_SERVER=https://your-workspace.ftrackapp.com
FTRACK_API_USER=your-username
FTRACK_API_KEY=your-api-key

The .env file is automatically loaded at startup and is excluded from git.

Option B: System Environment Variables (recommended for production)

The most secure approach is to set your credentials as system environment variables. The MCP server reads from these automatically.

Windows (PowerShell - run as Administrator):

[System.Environment]::SetEnvironmentVariable('FTRACK_SERVER', 'https://your-workspace.ftrackapp.com', 'User')
[System.Environment]::SetEnvironmentVariable('FTRACK_API_USER', 'your-username', 'User')
[System.Environment]::SetEnvironmentVariable('FTRACK_API_KEY', 'your-api-key', 'User')

Windows (GUI): Settings → System → About → Advanced system settings → Environment Variables

macOS/Linux (~/.bashrc or ~/.zshrc):

export FTRACK_SERVER="https://your-workspace.ftrackapp.com"
export FTRACK_API_USER="your-username"
export FTRACK_API_KEY="your-api-key"

After setting environment variables, restart your terminal/IDE.

Step 2: Configure Your MCP Client

#### Claude Desktop

Edit your config file:

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

{
  "mcpServers": {
    "ftrack": {
      "command": "node",
      "args": ["C:/path/to/ftrack-mcp/src/index.js"]
    }
  }
}

#### Cursor / VS Code

Add to your MCP settings or .cursor/mcp.json:

{
  "mcpServers": {
    "ftrack": {
      "command": "node",
      "args": ["/absolute/path/to/ftrack-mcp/src/index.js"]
    }
  }
}

Note: Use forward slashes (/) even on Windows.

Alternative: Credentials in Config (Less Secure)

If you can't set system environment variables, you can pass them through the MCP config:

{
  "mcpServers": {
    "ftrack": {
      "command": "node",
      "args": ["C:/path/to/ftrack-mcp/src/index.js"],
      "env": {
        "FTRACK_SERVER": "https://your-workspace.ftrackapp.com",
        "FTRACK_API_USER": "your-username",
        "FTRACK_API_KEY": "your-api-key"
      }
    }
  }
}

⚠️ Warning: This stores credentials in a config file. Make sure this file is not committed to version control.

Running Standalone (for testing)

npm start

Usage Examples

Once configured, you can ask Claude to interact with ftrack using natural language:

• "List all my ftrack projects"
• "Show me tasks assigned to John on the Marvel project"
• "Create a new task called 'Final Review' under shot SH010"
• "Update the status of task XYZ to 'In Progress'"
• "What's the storage usage for my workspace?"
• "List all versions for the compositing task"

Available Tools (55+)

Query Operations

CRUD Operations

Convenience Tools

User & Security Management

File & Media Operations

Review Sessions

API Key Management

2FA/Authentication

Delayed Jobs (Background Tasks)

ftrack Query Language Examples

The ftrack_query tool accepts ftrack's query language:

-- List all active projects
select id, name, status from Project where status is "active"

-- Get tasks assigned to a user
select id, name, status.name from Task
where assignments any (resource.username is "john")

-- Find shots in a sequence
select id, name from Shot where parent.name is "SEQ010"

-- Get latest versions for a task
select id, version, date, user.username from AssetVersion
where task_id is "abc-123" order by version descending

-- Search with wildcards
select id, name from Project where name like "%marvel%"

Troubleshooting

"Failed to initialize ftrack client"

• Verify your environment variables are set correctly
• Check that your API key is valid and not expired
• Ensure your ftrack server URL includes https://

"Connection refused" or timeout errors

• Check your network connection to ftrack
• Verify the server URL is correct
• Check if your workspace is accessible

"Permission denied" errors

• Your API key may not have sufficient permissions
• Contact your ftrack administrator to adjust your security role

Security Notes

• Never commit your API credentials to version control
• Use environment variables or secure secret management
• API keys have the same permissions as the user - use dedicated service accounts for automation
• Consider using project-scoped API keys for limited access

License

ISC

Contributing

Contributions are welcome! Please open an issue or submit a pull request.