Skip to main content
Glama
finns-flame-mcp
by dr1pvfx

Finn's Flame MCP

A local MCP server for Autodesk Flame finishing. This distribution combines the structured operations and journal from mnt0414, source-anchor diagnostics from Abraham's Flame MCP, and an exact-preview rename workflow using a manifest fingerprint adapted from Chris Nollert's forge-bridge.

  • Inspect editorial state. Read the focused shot with timeline.focused_shot. Use timeline.anchor_report to flag unusual source anchors. A trim can explain a difference, so verify flagged shots against the offline.

  • Review single renames. Send a stable Wiretap target and name to review.rename_preview. After reviewing the manifest, send its fingerprint to review.rename_apply. It re-reads the name and identity, then uses the journaled rename with a compare-and-swap precondition. Other upstream tools retain their operation-specific policy and journal behavior.

  • Trace calls. Set FINNS_FLAME_MCP_TRACE to a private JSONL file path to record operation names, parent spans, timing, errors and journal group IDs. Arguments, project paths, and response content stay out of this trace.

Install in a Python 3.11+ virtual environment and run scripts/install_bridge.sh with Flame closed. The MCP client command is finns-flame-mcp from that venv. For integrations, finns-flame-call reads one tool request on stdin and returns the structured reply from a real stdio MCP session.

The combined repository is licensed under GPL-3.0-only. Upstream licenses, pinned revisions and fork review are in THIRD_PARTY_NOTICES.md. The metadata below describes the inherited upstream operations. Check the qualification notes for actual release evidence.

What it does

flame-mcp works best for organizing projects and for routine tasks that follow fixed steps.

Action

Examples

Read

List libraries, reels, clips, and sequences. Read segments (video and audio), Batch nodes, and their attributes. Compare two sequences.

Organize

Create, duplicate, move, and rename reels, clips, and sequences. Delete clips and sequences.

Edit

Trim, slip, replace, and delete segments (closing the gap or leaving it). Cut, insert, and overwrite. Move video tracks. Shorten a sequence. Read and set segment connections. Add and set up Timeline FX.

Batch

Create, connect, and set up nodes. Save and load setups. Compare a setup with one saved earlier to find values changed by hand. Render.

Multi-step plans

Run several operations as one procedure (plan.run).

There are 115 operations in 14 categories. For the full list, see docs/ops.md.

Related MCP server: MCP Bridge for Adobe Premiere Pro

Before you start

CAUTION

The assistant changes your Flame project directly. Try it on a test project first. Before you let the assistant change an important project, archive the project.

What the assistant reads is sent to the AI service that your client uses. For details on what is sent, see Information sent to the AI service. Before you use flame-mcp on a project under an NDA, check the AI service's data retention policy and your client's logs.

Quick start

Requirements

OS

macOS

Flame

Upstream native results on 2025.2.4 and 2026.2.3. This preview registered its hook in 2027.1. See qualification.

Python

3.11 or later (for the server)

MCP client

A client that can run a local stdio server. Tested with Claude Code.

flame-mcp sends only ASCII characters to Flame. Use ASCII characters in the names and file paths that you ask the assistant to use. You can ask the assistant in any language.

1. Get the code and install the server.

git clone https://github.com/dr1pvfx/finns-flame-mcp.git
cd finns-flame-mcp
python3.12 -m venv .venv
.venv/bin/pip install -e .

Replace python3.12 with any installed Python 3.11 or later. The /usr/bin/python3 that comes with macOS can be older than 3.11.

2. Quit Flame, then install the bridge into Flame.

The installer copies two real files:

  • finns_flame_mcp_bridge.py: the entry point that Flame loads when it starts. It's installed in /opt/Autodesk/shared/python/.

  • impl.py: the main part of the bridge. It's installed in ~/Library/Application Support/finns-flame-mcp/bridge/.

If a file with the same name already exists, the installer backs it up before it overwrites the file.

scripts/install_bridge.sh --dry-run
scripts/install_bridge.sh
scripts/doctor.sh

With --dry-run, the installer writes nothing and only shows what it would change. If the output looks right, run install_bridge.sh. doctor.sh checks that the installation worked.

3. Register the server with your MCP client.

For Claude Code, run this command:

claude mcp add flame -- /path/to/finns-flame-mcp/scripts/flame_mcp_server.sh

For a client that uses a JSON settings file, put the path of flame_mcp_server.sh in command. After you edit the file, quit the client completely and start it again.

{
  "mcpServers": {
    "flame": {
      "command": "/path/to/finns-flame-mcp/scripts/flame_mcp_server.sh"
    }
  }
}

4. Check the connection.

Start Flame, open a project, and give the assistant a simple request that changes nothing:

"What is the name of the project that's open in Flame? Don't change anything in the project."

If the assistant tells you the project name, the connection works. If it doesn't, see Troubleshooting.

Example requests

Start with requests that only read. Then try a change whose result you can check quickly.

"List the reels on the Desktop and the clips in each one."

"In this sequence, replace the third segment on V1 with the clip I just imported. Match the source timecode to the original."

"Extract each segment of this sequence to a reel, with 10-frame handles."

"Load this setup into the current Batch group, and tell me the range before you render."

Requests that name the target, the action, and how to check the result usually work better than vague requests such as "make it better."

Uninstall

Quit Flame, then run these commands:

scripts/uninstall_bridge.sh --dry-run
scripts/uninstall_bridge.sh

The script removes two files, flame_mcp_bridge.py and impl.py. It backs them up before it removes them.

The change records, the files saved for undo, and the logs stay. For what stays and where it is stored, see Stored files and retention periods. You can delete these files manually if you no longer need them.

The server's registration in your MCP client also stays. In Claude Code, remove it with this command:

claude mcp remove flame

Safety and privacy

Information sent to the AI service

flame-mcp itself sends nothing over the internet. It doesn't collect usage data (telemetry).

What the assistant receives from flame-mcp becomes part of the conversation, and your MCP client sends it to the AI service. This includes the following:

  • Names of projects, libraries, reels, clips, sequences, and nodes

  • Parameter values of Batch nodes (numbers, and also text such as node names and the output path of a Write File node)

  • File paths (they can include your user name)

  • Metadata such as timecode

  • Lines from Flame's logs

No flame-mcp operation reads images, except eval.run. When eval.run is turned on, any file, including images, can be read.

If your client uses a model that runs on your computer, the conversation can stay on your computer. Whether the client sends anything else depends on the client and its settings.

Asking before an operation runs

Your MCP client's settings decide whether the assistant asks you before it runs an operation. On the flame-mcp side, you can limit which operations the assistant can use (see Configuration). flame-mcp also checks every call before it sends anything to Flame.

Text in a project that steers the assistant

Clip names, metadata, the contents of setups, and Flame's logs are passed to the assistant as they are. If they contain text that reads like instructions to an AI, the assistant might follow those instructions (prompt injection). To look through a project that you received from someone else, use read-only mode.

Safeguards in flame-mcp

  • flame-mcp records each change before it sends the change to Flame.

  • Operations that overwrite files (overwrite=true, or a render onto existing frames) are treated as destructive. If destructive isn't in FLAME_MCP_ALLOW_EFFECTS, flame-mcp refuses them. flame-mcp also tells the assistant to ask you before it runs an operation that overwrites or can't be undone. flame-mcp can't check that you agreed, so this depends on the assistant and your client.

  • journal.purge_checkpoints deletes the copies saved for undo. It first runs as a dry run, and it deletes only when it receives the token that the dry run showed.

  • If a call ends without an answer (TIMEOUT, BRIDGE_LOST), flame-mcp refuses changes until the assistant has checked the actual state.

  • flame-mcp sends only ASCII characters to Flame. If a name, path, or piece of code contains a non-ASCII character, flame-mcp refuses the call and sends nothing.

  • eval.run, which runs arbitrary Python code, is turned off by default (see Running arbitrary Python code).

Other programs running as the same user

The bridge accepts connections only from the user who started Flame, and it runs the code that it receives. flame-mcp's settings limit only the operations that come through the MCP client. They can't limit what another program running as the same user sends to the bridge directly. This includes an assistant that can use a shell (terminal). Don't let an assistant that you don't trust use a shell on the computer where Flame runs.

Computers shared by several users

flame_mcp_bridge.py is installed in /opt/Autodesk/shared/python/, and every user and every Flame version on the computer loads it. If other users can write to this folder, they can replace flame_mcp_bridge.py. Check the folder's permissions. flame_mcp_bridge.py doesn't load the main part of the bridge, impl.py, if other users can change impl.py or its folder.

Stored files and retention periods

flame-mcp creates its files on disk so that only the user who started Flame can read them (files 0600, folders 0700). At start-up, flame-mcp also tightens the permissions of what already exists in its own folder (see docs/safety.md).

What

Where

How long

Records of the changes that the assistant made

~/Library/Application Support/finns-flame-mcp/journal/

30 days

Batch setup files saved for undo

journal/checkpoints/

Not deleted automatically

Copies saved for undo, made before the assistant deletes or edits a clip or sequence

The flame_mcp_checkpoints library in each project

Until they are deleted with journal.purge_checkpoints

Operation results too large to return to the assistant directly (over about 60 KB; the assistant receives only the location of the file)

~/Library/Application Support/finns-flame-mcp/spill/

7 days (when the server starts, it deletes files older than 7 days)

Bridge logs

~/Library/Application Support/finns-flame-mcp/logs/

Up to 4 files (when a file reaches 2 MB, the bridge starts a new file and deletes the oldest one)

Undo

To undo a change, ask the assistant ("Undo the last change"). The assistant runs journal.revert, which uses the change record to put things back. If a change can't be undone one value at a time, journal.revert uses the setup files or the copies saved for undo. If the target changed after the assistant's change, journal.revert stops and doesn't overwrite it.

Changes made in one plan.run are undone together.

WARNING

After the assistant changes something, don't press Ctrl+Z. Flame's undo history doesn't always record changes such as renames and attribute changes. If you press Ctrl+Z, Flame might undo an earlier, different action instead.

The following can't be undone. The description of each operation in docs/ops.md says whether it can be undone.

  • Files written by a render, by render.export or by render.still, the clips that the render created, and the Timeline FX that render.clip rendered

  • Saved setup files

  • Shelf reels and Batch iterations that were created

  • Copies saved for undo that were deleted with journal.purge_checkpoints

  • Changes that the setup file saved for undo doesn't cover (for example, another Batch group or the Desktop)

When a change is undone from a setup file saved for undo, flame-mcp can't detect attribute values or node positions that you changed by hand afterward. Undoing can also remove those manual changes.

For details, see docs/safety.md.

Configuration

Usually, you don't need to configure anything. To change a setting, pass an environment variable to the server in your MCP client's settings.

Variable

Default

Meaning

FLAME_MCP_READONLY

Off

1: use only operations that don't change or write anything

FLAME_MCP_ALLOW_CATEGORIES

All

The categories that can be used, separated by commas (for example, library,desktop,timeline,segment,journal)

FLAME_MCP_ALLOW_EFFECTS

All

The effects that can be used, separated by commas (read, reversible, create, destructive)

FLAME_MCP_ENABLE_EVAL

Off

1: turn on eval.run

FLAME_MCP_CHECKPOINT_LIBRARY

flame_mcp_checkpoints

The library where copies saved for undo are kept

FLAME_MCP_RESPONSE

full

compact: send smaller responses to the assistant (see Smaller responses)

FLAME_MCP_FFMPEG

Search the PATH, then the imageio_ffmpeg package

The ffmpeg that render.still uses to make its PNG

FLAME_MCP_STILLS_DIR

~/Library/Application Support/finns-flame-mcp/stills

Where render.still puts its files

FLAME_MCP_PRESETS_DIR

/opt/Autodesk/presets

The directory that holds Flame's export presets, one folder per Flame version; render.still reads its preset from there

  • Include read in FLAME_MCP_ALLOW_EFFECTS. Without it, every read is refused too.

  • Without journal in FLAME_MCP_ALLOW_CATEGORIES, the assistant can't check its changes or undo them.

  • If a setting isn't valid (for example, FLAME_MCP_READONLY=true, or a list that has only commas), the server doesn't start, and it shows the reason.

Read-only mode

Use read-only mode to review or audit a project without changing anything.

{
  "mcpServers": {
    "flame": {
      "command": "/path/to/finns-flame-mcp/scripts/flame_mcp_server.sh",
      "env": { "FLAME_MCP_READONLY": "1" }
    }
  }
}

Only operations that change nothing are listed, and only they can run. eval.run is refused. To read a closed library by name, the server opens the library, reads it, and closes it again.

Smaller responses

With FLAME_MCP_RESPONSE=compact, the server leaves out of each response what the assistant can do without, so the conversation uses fewer tokens. The values that are sent don't change.

  • Fields that are empty (null, an empty list or object, an empty string) aren't sent. execution is sent only when a call fails.

  • Inside result, members that are null aren't sent, and neither is a wiretapId that repeats the selector next to it.

  • A list of three or more objects of the same shape is sent as a table, {columns, rows}.

  • What the assistant passes back to undo or repeat a call (revert, inverse, args) keeps its full form.

The server explains this form to the assistant in its instructions and in flame_context (responseFormat).

{
  "mcpServers": {
    "flame": {
      "command": "/path/to/finns-flame-mcp/scripts/flame_mcp_server.sh",
      "env": { "FLAME_MCP_RESPONSE": "compact" }
    }
  }
}

In either mode, desktop.list_children, desktop.list_all, desktop.find, and timeline.list_segments take fields, the members of each item to return (for example ["name", "uid"]). An item that couldn't be read keeps its error. A name that the operation's items never have is refused with INVALID_ARGS.

Running arbitrary Python code (eval.run)

eval.run is the last resort, for tasks that no operation can do. It's available only when FLAME_MCP_ENABLE_EVAL=1 is set, and it's never available in read-only mode.

CAUTION

eval.run runs arbitrary Python code inside Flame, with the permissions of the user who started Flame. The code can read, write, and delete files, use the network, and start processes. A static check stops common mistakes, but it isn't a sandbox, and deliberately written code can get past it. A timeout only stops waiting for the code to finish. It doesn't stop the code. Code that never finishes can leave Flame not responding. Turn on eval.run only when you trust both the assistant and the project.

Troubleshooting

The assistant can't connect to Flame (BRIDGE_UNAVAILABLE)

  1. Start Flame and open a project. The bridge accepts connections after a project is open.

  2. In Flame's main menu, choose MCP Bridge > Show status to check that the bridge is running. If it shows Bridge is not running., choose Show last error to see why.

  3. If the main menu has no MCP Bridge, Flame didn't load the bridge. Quit Flame, run install_bridge.sh, and start Flame again. To check the installation, run scripts/doctor.sh.

While Batch is rendering, the assistant might not be able to connect until the render finishes.

Multiple instances of Flame are running (BRIDGE_AMBIGUOUS)

If the bridge is running in more than one instance of Flame, flame-mcp doesn't connect to any of them. This keeps it from changing the wrong instance. Quit the instances of Flame that you aren't using.

An operation stopped responding (TIMEOUT, BRIDGE_LOST)

When this error appears, flame-mcp can't tell whether the change took effect. The assistant doesn't make another change until it has checked the actual state.

BRIDGE_LOST means that Flame might have crashed. If Flame has quit, start it again, and then ask the assistant to check the state.

A change had no effect (SILENT_NOOP)

Check whether a dialog is open in Flame. While a dialog is open, some changes to the Media Panel might not take effect. Close the dialog, and then ask the assistant again.

The flame tools don't appear in the client

  • Quit the client completely, including any process left in the menu bar or the system tray, and start it again.

  • Check the path of flame_mcp_server.sh in the client's settings.

  • If an environment variable has a value that isn't valid, the server doesn't start. Check Configuration.

A call is refused with non-ASCII character

flame-mcp can send only ASCII characters to Flame. You can still ask the assistant in any language. Use ASCII characters in the names of clips and nodes, and in file paths.

The server doesn't start and shows non-ASCII character for the journal directory

The path of the folder where flame-mcp keeps its change records contains a character that isn't ASCII. flame-mcp puts this path in the code that it sends to Flame, so the path must be ASCII. Set the environment variable FLAME_MCP_JOURNAL_DIR to a folder path that uses only ASCII characters. For how to pass an environment variable, see Configuration.

The assistant says it can't do something

  • If you limited the operations in Configuration, the assistant doesn't see the operations that you excluded.

  • The assistant might answer without looking for an operation. Ask it to search with flame_catalog.

  • If no operation fits, flame-mcp can't do that task. For the list of operations, see docs/ops.md.

If the problem continues

Report it in GitHub Issues. The following information helps find the cause:

  • Your Flame and macOS versions

  • The output of scripts/doctor.sh

  • What MCP Bridge > Show last error shows

  • The relevant part of ~/Library/Application Support/finns-flame-mcp/logs/bridge.log (it contains file paths and project names, so paste only the parts that you're comfortable making public)

Report security vulnerabilities as described in SECURITY.md, not in Issues.

Limitations

  • Not supported:

    • markers

    • transitions

    • editing keyframes

    • Save Desktop (putting a copy of the Desktop into a library). To save the project, use project.save

    • deleting folders, and deleting reels that hold anything (an empty Desktop reel can be deleted)

    • Linux

  • render.export writes only into an empty directory and never overwrites. Use a new directory for each export.

  • render.export and render.still can't be undone. The files that they write stay on disk. The PNG of render.still is a small image for checking, not a deliverable.

  • You can't delete anything in a library, or move anything out of a library. This keeps past work stored in libraries from being changed by mistake. To take something out of a library, use desktop.copy (the original stays).

  • A sequence or clip that's restored by an undo goes to the end of its reel. To change the order of a Desktop reel, use desktop.reorder. The entries that it moves get new uids. To undo a change to a sequence, flame-mcp replaces the sequence with the copy that it saved before the change. The changed sequence isn't deleted. It moves to the library for undo copies (flame_mcp_checkpoints).

  • The flame_context tool lists known pitfalls in its pitfalls field.

How it works

MCP client  <-- stdio -->  flame-mcp server  <-- Unix socket -->  bridge inside Flame  -->  Flame Python API

The server gives the assistant four tools. The assistant calls these tools itself, and you don't use them directly. Most work uses two of them: the assistant finds an operation with flame_catalog and runs it with flame_do.

Tool

What the assistant uses it for

Changes the project

flame_catalog

Find the operations that it can use, and read their descriptions

No

flame_do

Run one operation

Depends on the operation

flame_context

Learn the working rules and Flame's current state

No

flame_version_info

Check the connection and the settings

No

For details, see docs/architecture.md.

Documentation

Document

Contents

docs/ops.md

Every operation, with its effect and whether it can be undone (generated)

docs/architecture.md

How the server, the bridge, and the change records work

docs/safety.md

What is undone and how, what can't be undone, and how to read each error

docs/testing.md

How to run the tests, and what each regression test on a real Flame checks

Development

.venv/bin/pip install -e '.[dev]'
.venv/bin/python -m pytest

The unit tests in tests/ run without Flame. The regression tests on a real Flame are in scripts/regress.sh. Because they change Flame, they run only in a dedicated test project. For setup and instructions, see docs/testing.md.

Questions, requests, and bug reports

Ask questions, make requests, and report bugs in GitHub Issues. A usage report helps too, even when nothing went wrong: the Flame version, the kind of work, and what was missing. One line is enough, and you can write in any language. To propose a code change, discuss it in an issue before you open a pull request. For how to contribute, see CONTRIBUTING.md.

Acknowledgments

Trademarks

Autodesk and Flame are registered trademarks or trademarks of Autodesk, Inc. This project is an independent, unofficial tool. It isn't affiliated with Autodesk, Inc., and it isn't endorsed or supported by Autodesk.

License

GPL-3.0-only. See LICENSE.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to control Autodesk Flame through MCP using multiple execution paths such as the Flame Python API, native commands, raw Python, UI automation, and other tools, with observation and verification of results.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables MCP clients to operate local Adobe Premiere Pro projects, covering media ingest, bins, sequence and timeline editing, transitions, effects, keyframes, captions, markers, metadata, proxies, multicam, color, audio, and exports through 283 discoverable tools, 13 context resources, and 10 guided prompts. A bundled CEP panel provides the supported production bridge, with read-only connection verification and higher-level workflows for assembling product spots and motion-graphics demos.
      5
      MIT
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables an MCP client like Claude to read, edit, and generate real Final Cut Pro timelines from exported FCPXML, covering cut and flash-frame detection, silence and gap removal, markers, keyframes, speed ramps, transcript-based editing, cross-NLE export, and pushing the result into a running Final Cut Pro. Every write is journaled with its sha256 so changes can be undone and unreviewed cuts refused.
      -
    • A
      license
      A
      quality
      C
      maintenance
      A read-only MCP server that lets an agent decompile Final Cut Pro FCPXML timelines into compact briefs, resolve multicam angles, compounds and retimes exactly, and run safety checks for transition handles, jump-cut dissolves, missing effects, relink problems and timeline diffs. It also supports applying edits from an annotated brief and guarded, plan-and-ledger-checked imports into a named library, always writing to new files and reporting anything unverifiable as REVIEW rather than passing.
      8
      MIT