assimilate-mcp

<div align="center"> <pre> ▄▀█ █▀ █▀ █ █▀▄▀█ █ █ ▄▀█ ▀█▀ █▀▀ █▀▄▀█ █▀▀ █▀█ █▀█ ▄█ ▄█ █ █ ▀ █ █ █▄▄ █▀█ █ ██▄ █ ▀ █ █▄▄ █▀▀ </pre>

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

<br>

<a href="https://www.npmjs.com/package/assimilate-mcp"><img src="https://img.shields.io/npm/v/assimilate-mcp?style=for-the-badge&labelColor=000&color=CB3837" alt="npm"></a>  <a href="LICENSE"><img src="https://img.shields.io/badge/license-ELv2-3B82F6?style=for-the-badge&labelColor=000" alt="License"></a>  <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-server-8B5CF6?style=for-the-badge&labelColor=000" alt="MCP Server"></a>  <a href="https://claude.ai/download"><img src="https://img.shields.io/badge/Claude_Desktop-ready-D97706?style=for-the-badge&labelColor=000" alt="Claude Desktop"></a>  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D_18-339933?style=for-the-badge&labelColor=000" alt="Node.js"></a>  <img src="https://img.shields.io/badge/tools-85-22C55E?style=for-the-badge&labelColor=000" alt="85 Tools">

<br> <br>

Model Context Protocol server for Assimilate Live FX / SCRATCH,<br>designed for Claude Desktop. Complete 1:1 integration of the<br>Assimilate REST API — 85 tools across 14 categories.

</div> <br>

What is this?

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

Instead of clicking through menus, you describe what you want and Claude 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 Claude 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 like Claude Desktop talk to external software. Think of it like a plugin system — MCP servers give Claude new abilities by connecting it to tools and services it couldn't access on its own.

In this case, AssimilateMCP connects Claude 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 Claude can use. 85 tools total, covering every endpoint.

AssimilateMCP is a standard MCP server, so it works with any MCP-compatible client. The easiest and most user-friendly way to use it is with Claude Desktop — that's what this guide covers.

You (natural language) → Claude Desktop → AssimilateMCP → Live FX / SCRATCH

You talk to Claude. Claude 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:

<table> <tr><td><strong>macOS</strong></td><td><strong>Windows</strong></td></tr> <tr><td>

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.

</td><td>

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

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

</td></tr> </table>

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"]
    }
  }
}

<details> <summary><strong>Alternative: install from source</strong></summary> <br>

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.

</details>

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 85 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.

<details> <summary><strong>It's not working?</strong></summary> <br>

| 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

</details>

---

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

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

| Category | Count | Examples | |----------|:-----:|---------| | System | 7 | get_system list_users select_user create_user | | Projects | 7 | list_projects enter_project create_project | | Groups | 8 | list_groups get_current_group move_group create_group | | Constructs | 9 | 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 | — | | --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 |

---

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 user@192.168.1.50

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.

<details> <summary><strong>Persistent tunnel setup</strong></summary> <br>

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

</details>

---

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) |

Logs — Claude Desktop writes MCP server logs here:

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

---

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.

---

<div align="center">

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

<br>

Elastic License 2.0 (ELv2)

Built by Rogue Labs

</div>