Add AI control to your virtual production studio and post-production pipeline.

Model Context Protocol server for Assimilate Live FX / SCRATCH.Works with Claude Desktop, VS Code, Cursor, Windsurf, OpenClaw, and any MCP client.Complete 1:1 integration of the Assimilate REST API — 88 tools across 14 categories.

What is this?

AssimilateMCP lets you control Assimilate Live FX / SCRATCH by talking to AI in plain English.

Instead of clicking through menus, you describe what you want and your AI assistant does it:

• "Import today's footage from /Volumes/Media/Day_12 and create a new group called Day 12 Dailies"
• "Create ProRes dailies with a timecode burn-in"
• "Composite this green screen shot"
• "The gamma feels cold on this whole sequence — warm it up across all the shots"
• "Step through each shot and take a snapshot for the director"

Dailies, grading, compositing, rendering deliverables — describe the workflow in your own words and the AI handles the rest. No commands to memorize, no scripting.

How does it work?

AssimilateMCP is an MCP server. MCP (Model Context Protocol) is an open standard that lets AI apps talk to external software. Think of it like a plugin system — MCP servers give AI assistants new abilities by connecting them to tools and services they couldn't access on their own.

In this case, AssimilateMCP connects your AI assistant to the Assimilate REST API, which is the programmatic interface built into Live FX and SCRATCH. Every feature the REST API exposes — projects, timelines, color grading, playback, rendering, outputs, file management — becomes a tool the AI can use. 88 tools total, covering every endpoint.

AssimilateMCP works with any MCP-compatible client: Claude Desktop, VS Code (GitHub Copilot), Cursor, Windsurf, OpenClaw, and more. See Compatible Clients for setup instructions. The Getting Started guide below uses Claude Desktop as the example.

You (natural language) → AI Client → AssimilateMCP → Live FX / SCRATCH

You talk to your AI assistant. The AI talks to AssimilateMCP. AssimilateMCP talks to Live FX. Everything happens in real time on your local machine.

Getting Started

You'll need three things installed before you begin:

| | | |---|---| | Assimilate Live FX or SCRATCH | v9.9+ with REST API enabled | | Claude Desktop | Download and install if you haven't already | | Node.js | v18 or later — download the LTS version |

[!NOTE] The REST API is currently available with a special beta build. See the Assimilate REST API documentation for details, or contact Assimilate Support for access.

Step 1 — Enable the REST API in Live FX

1. Open Live FX or SCRATCH
2. Go to System Settings → General
3. Check Enable HTTP Server
4. Leave the port as 8080 (default) or note the port you choose
5. Click Apply

Step 2 — Add AssimilateMCP to Claude Desktop

Claude Desktop needs a small config file that tells it where to find MCP servers. You only do this once.

Open the config file:

Open Claude Desktop, then go to Claude (menu bar) → Settings → Developer → Edit Config

This opens claude_desktop_config.json in your default editor. If the file is empty or doesn't exist yet, that's normal.

Open Claude Desktop, then go to File → Settings → Developer → Edit Config

Or open the file manually at %APPDATA%\Claude\claude_desktop_config.json

Paste this into the file:

{
  "mcpServers": {
    "assimilate": {
      "command": "npx",
      "args": ["-y", "assimilate-mcp"]
    }
  }
}

That's it. Claude Desktop will automatically download and run AssimilateMCP when it starts.

Save the file and close the editor.

[!TIP] Already have other MCP servers configured? Don't replace the whole file. Add the "assimilate": { ... } block inside your existing "mcpServers" object, separated by a comma:

{
  "mcpServers": {
    "some-other-server": { "..." },
    "assimilate": {
      "command": "npx",
      "args": ["-y", "assimilate-mcp"]
    }
  }
}

If Claude Desktop can't find npx on Windows, add the Node.js path explicitly:

{
  "mcpServers": {
    "assimilate": {
      "command": "npx",
      "args": ["-y", "assimilate-mcp"],
      "env": {
        "PATH": "C:\\Program Files\\nodejs;%PATH%"
      }
    }
  }
}

Or use the full path to npx:

{
  "mcpServers": {
    "assimilate": {
      "command": "C:\\Program Files\\nodejs\\npx.cmd",
      "args": ["-y", "assimilate-mcp"]
    }
  }
}

npx downloads AssimilateMCP on every launch. For faster startup, install it globally once:

npm install -g assimilate-mcp

Then use this config (no npx, no -y):

{
  "mcpServers": {
    "assimilate": {
      "command": "assimilate-mcp"
    }
  }
}

To update later: npm update -g assimilate-mcp

If you prefer to clone the repo and build locally:

git clone https://github.com/amac-roguelabs/assimilate-mcp.git
cd assimilate-mcp
npm install
npm run build

Then use this config instead, replacing the path with where you cloned the repo:

{
  "mcpServers": {
    "assimilate": {
      "command": "node",
      "args": ["/path/to/assimilate-mcp/dist/index.js"]
    }
  }
}

Not sure what your full path is? Run echo "$(pwd)/dist/index.js" from the repo folder and paste the output into the "args" array.

Step 4 — Restart Claude Desktop

Fully quit Claude Desktop (Cmd+Q on macOS, Alt+F4 on Windows) and reopen it. A simple close isn't enough — the app needs to fully restart to pick up the new config.

After restarting, look for the hammer icon in the bottom-right of the chat input box. Click it — you should see AssimilateMCP and its 88 tools listed. If you see the hammer icon, the server is loaded.

Step 5 — Connect to Live FX

Make sure Live FX is running with the HTTP server enabled (Step 1), then ask Claude:

"What projects are available?"

If Claude responds with a list of projects from Live FX, everything is working.

| Symptom | Fix | |---------|-----| | No hammer icon in Claude Desktop | The config file has a syntax error. Open it and check for missing commas, brackets, or quotes. JSON must be valid. | | Hammer icon shows but tools fail | Make sure Live FX is running and the HTTP server is enabled in System Settings → General. | | "Connection refused" errors | Check that the port matches (default 8080). If you changed it in Live FX, add "--port", "YOUR_PORT" to the args array. | | "Cannot find module" error | The path in your config is wrong. Double-check it matches where you cloned the repo, and that you ran npm run build. |

Check the logs for detailed error messages:

macOS:

cat ~/Library/Logs/Claude/mcp-server-assimilate.log

Windows:

%APPDATA%\Claude\logs\mcp-server-assimilate.log

Examples

Here's a sample of what you can do. These aren't special commands — just plain English.

Dailies & Review

• "Import all the ARRIRAW files from /Volumes/Shuttle/Day_14"
• "Create a group called Day 14 Selects and add the circled takes"
• "Play through the timeline and stop at any shot longer than 5 seconds"
• "Take a snapshot of this frame so I can send it to the director"

Color Grading

• "Show me the grade on shot 3"
• "The whole sequence is a bit cool — warm up the gamma"
• "Push the lift toward blue and pull the gain toward warm"
• "Copy the grade from shot 5 and apply it to shots 6 through 10"

Compositing & VFX

• "Composite this green screen shot"
• "Add a clean plate as a second input on shot 12"
• "What inputs does this shot have?"
• "Set the framing to reposition the subject"

Rendering & Deliverables

• "Create ProRes dailies with a timecode burn-in"
• "Set up a ProRes 4444 output at /Volumes/Render/Episode_3"
• "Render the full timeline"
• "How's the render going? How many shots are left?"

Project Management

• "What projects are available?"
• "Create a new project called Commercial_Nike_Q3"
• "List all the groups in this project"
• "Show me what constructs are in the VFX group"

Media & File Management

• "Find all EXR sequences on /Volumes/Media"
• "Import the RED files from /Volumes/Camera/A_Cam"
• "Move version 2 to the next slot"
• "List everything in /Volumes/Shuttle"

Tools

88 tools — complete coverage of every endpoint in the Assimilate REST API.

| Category | Count | Examples | |----------|:-----:|---------| | System | 8 | get_system list_users select_user create_user check_connection | | Projects | 7 | list_projects enter_project create_project | | Groups | 9 | list_groups get_current_group move_group create_group | | Constructs | 10 | list_constructs create_construct move_current_construct | | Slots | 5 | list_slots get_slot set_slot create_slot | | Versions | 5 | list_versions get_version set_version move_version | | Shots | 7 | get_shot set_shot create_shot import_media | | Inputs | 4 | get_inputs get_input set_input delete_input | | Color Grading | 5 | get_grade set_grade get_framing set_framing | | Player | 8 | enter_timeline set_playmode enter_shot exit_player | | Render | 10 | start_render stop_render start_render_item stop_render_item | | Outputs | 6 | list_outputs create_output set_output | | Snapshots | 2 | render_snapshot get_shot_metadata | | Files | 2 | list_directory find_media |

Architecture

flowchart LR
    A["Claude Desktop"] -- "stdio / MCP" --> B["AssimilateMCP"]
    B -- "HTTP :8080" --> C["Live FX / SCRATCH"]

AssimilateMCP speaks the Model Context Protocol over stdio. Claude Desktop launches the server, sends tool calls, and AssimilateMCP translates them into HTTP requests against the REST API running inside Live FX / SCRATCH.

Data Model

The Assimilate data hierarchy maps directly to the tool categories:

System
  └── Project
       └── Group
            └── Construct (Timeline)
                 ├── Slot
                 │    └── Version (Shot)
                 │         ├── Color Grade
                 │         ├── Framing
                 │         ├── Inputs (Source Layers)
                 │         └── Animation
                 └── Output Nodes

Configuration

CLI Options

Pass these as additional args in your Claude Desktop config:

"args": ["/path/to/dist/index.js", "--port", "9090", "--key", "mykey"]

| Flag | Description | Default | |------|-------------|---------| | --host | Live FX host | 127.0.0.1 | | --port | Live FX REST API port | 8080 | | --key | REST API authorization key | — | | --timeout | HTTP request timeout (ms) | 30000 | | --verbose -v | Verbose logging | off |

Environment Variables

| Variable | Description | |----------|-------------| | ASSIMILATE_HOST | Live FX host | | ASSIMILATE_PORT | Live FX REST API port | | ASSIMILATE_KEY | REST API authorization key | | ASSIMILATE_TIMEOUT | HTTP request timeout (ms) |

Connection Scenarios

Same Machine (Default)

Claude Desktop and Live FX on the same computer — no extra configuration needed. Connects to localhost:8080.

Different Port

Add "--port", "9090" to the args array in your Claude Desktop config.

Remote Machine

Live FX only accepts connections from localhost, so you need an SSH tunnel from the machine running Claude Desktop:

ssh -f -N -L 8080:127.0.0.1:8080 [email protected]

Then use the default config — Claude Desktop connects to localhost:8080 which tunnels to the remote machine.

For machines on different networks, use Tailscale or any VPN, then tunnel via the VPN IP.

Add to ~/.ssh/config:

Host livefx
    HostName 192.168.1.50
    User your-username
    LocalForward 8080 127.0.0.1:8080
    ServerAliveInterval 60
    ServerAliveCountMax 3

Then: ssh -f -N livefx

Troubleshooting

| Problem | Solution | |---------|----------| | No hammer icon after restart | Config file has a JSON syntax error — check for missing commas or brackets | | "Server not found" | Make sure Node.js is installed, then fully restart Claude Desktop | | "Connection refused" | Live FX isn't running, or the port doesn't match (default: 8080) | | "Cannot find module" | The path in your config is wrong — run echo "$(pwd)/dist/index.js" from the repo folder | | Tools appear but return errors | Check that Enable HTTP Server is on in Live FX System Settings → General | | Using a different port | Add "--port", "YOUR_PORT" to the args array in your Claude Desktop config | | Live FX on another machine | Set up an SSH tunnel (see Connection Scenarios) | | Windows: "npx is not recognized" | Node.js isn't in your PATH. See the Windows: npx not found? section above for the env workaround | | Windows: timeout errors on large renders | Increase the timeout: add "--timeout", "120000" to the args array (120 seconds) |

Logs — Claude Desktop writes MCP server logs here:

| | | |---|---| | macOS | ~/Library/Logs/Claude/mcp-server-assimilate.log | | Windows | %APPDATA%\Claude\logs\mcp-server-assimilate.log |

Compatible Clients

AssimilateMCP is a standard MCP server — it works with any MCP-compatible client, not just Claude Desktop. The same npx -y assimilate-mcp command works everywhere.

VS Code (GitHub Copilot)

Add to your VS Code settings.json (Cmd+Shift+P → "Open User Settings (JSON)"):

{
  "mcp": {
    "servers": {
      "assimilate": {
        "command": "npx",
        "args": ["-y", "assimilate-mcp"]
      }
    }
  }
}

Or create .vscode/mcp.json in your project root for workspace-scoped config:

{
  "servers": {
    "assimilate": {
      "command": "npx",
      "args": ["-y", "assimilate-mcp"]
    }
  }
}

MCP tools are available in Copilot's Agent mode (select "Agent" in the chat dropdown).

Cursor

Create ~/.cursor/mcp.json (global) or .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "assimilate": {
      "command": "npx",
      "args": ["-y", "assimilate-mcp"]
    }
  }
}

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json (or open via MCP icon → Configure → Advanced MCP Settings):

{
  "mcpServers": {
    "assimilate": {
      "command": "npx",
      "args": ["-y", "assimilate-mcp"]
    }
  }
}

Restart Windsurf after saving.

Cline (VS Code Extension)

Click the MCP Servers icon in Cline's sidebar → Configure MCP Servers, then add:

{
  "mcpServers": {
    "assimilate": {
      "command": "npx",
      "args": ["-y", "assimilate-mcp"]
    }
  }
}

Continue.dev

Add to your .continue/config.yaml:

mcpServers:
  - name: assimilate
    command: npx
    args:
      - "-y"
      - "assimilate-mcp"

MCP tools are only available in Continue's Agent mode.

OpenClaw

OpenClaw is an open-source personal AI assistant that runs 24/7 on your own hardware. It connects to messaging platforms (Telegram, WhatsApp, Slack, Discord) and can control Assimilate via MCP. Also available on ClawHub.

OpenClaw uses MCP servers through the MCPorter skill. Install it first, then register AssimilateMCP:

mcporter config add assimilate --command npx --args '["-y", "assimilate-mcp"]'

To verify it's registered:

mcporter config list

Or add it manually to config/mcporter.json:

{
  "mcpServers": {
    "assimilate": {
      "command": "npx",
      "args": ["-y", "assimilate-mcp"]
    }
  }
}

Once configured, your OpenClaw agent can use all 88 Assimilate tools — control Live FX via Telegram, Slack, or any connected channel.

Summary

| Client | Config File | Notes | |--------|-------------|-------| | Claude Desktop | claude_desktop_config.json | Best supported — see Getting Started | | VS Code | settings.json or .vscode/mcp.json | Copilot Agent mode required | | Cursor | ~/.cursor/mcp.json | Global or project-scoped | | Windsurf | ~/.codeium/windsurf/mcp_config.json | Restart after config change | | Cline | VS Code extension settings | UI-based setup | | Continue.dev | .continue/config.yaml | YAML format, Agent mode only | | OpenClaw | MCPorter skill → mcporter.json | Requires MCPorter — ClawHub · GitHub |

[!TIP] All clients use the same underlying MCP protocol. If your preferred AI tool supports MCP, AssimilateMCP will work with it — just point it at npx -y assimilate-mcp.

Development

git clone https://github.com/amac-roguelabs/assimilate-mcp.git
cd assimilate-mcp
npm install
npm run build
npm start -- --verbose

See CONTRIBUTING.md for guidelines on submitting changes.

Assimilate REST API · Assimilate Inc · Claude Desktop · Model Context Protocol · ClawHub

Elastic License 2.0 (ELv2)

Built by Rogue Labs