flame-mcp

flame-mcp

Control Autodesk Flame with natural language using Claude and the Model Context Protocol (MCP).

[!WARNING] Experimental project — use at your own risk. This is an independent, unofficial experiment created with Claude Code. It is not affiliated with, endorsed by, or officially supported by Autodesk in any way. The Flame name and trademarks belong to Autodesk, Inc.

Executing AI-generated code inside a live Flame session carries real risks: unexpected crashes, loss of unsaved work, unintended modifications to projects, sequences, or media. Always work on a duplicate or test project. Never run this on production material without a full backup. The author(s) accept no responsibility for data loss, corruption, or any other damage resulting from its use.

📊 Code knowledge graph

Interactive, auto-published map of this codebase — modules, functions, call/import edges and community clusters — rebuilt by graphify and deployed to GitHub Pages on every push to src/:

abrahamadsk.github.io/flame-mcp · part of the MCP ecosystem graph hub.

flame-mcp connects Claude to Autodesk Flame via a lightweight Python bridge. Type what you want to do in plain language — Claude translates it into Flame API calls and executes them live.

You: "Delete all reels named TEST from Default Library"
Claude → MCP Server → Unix socket → Flame Python API → Result back to Claude

---

Features

The system has two components:

hooks/flame_mcp_bridge.py — A Flame Python hook that starts a local UNIX domain socket server when Flame launches, restricted to its owner (0600 socket file — inside a 0700 run/ directory in a dev tree, in /tmp for the installed hook) and additionally checking the connecting process's UID. It receives Python code, executes it inside Flame's Python interpreter with full access to the flame module, and returns the result. There is no TCP transport: what arrives here is executed, so the socket's file permissions are the access control, and a loopback TCP socket has no owner the kernel could check.

src/flame_mcp/server.py — An MCP server that Claude launches. It exposes tools that Claude can call by name, translates natural language into Python code, and communicates with the bridge over the socket.

┌──────────────────┐    MCP (stdio)    ┌──────────────────────┐  Unix socket   ┌─────────────────┐
│  Claude Code /   │ ◄──────────────── │  flame_mcp/server    │ ◄────────────  │  Autodesk Flame │
│  Claude Desktop  │ ─────────────────►│   (Python, macOS)    │ ─────────────► │  Python bridge  │
└──────────────────┘                   └──────────────────────┘  (TCP fallback) └─────────────────┘

Compatible with Claude Code (terminal), Claude Desktop, and Cowork — all three contexts use the same MCP server and behave identically.

---

Requirements

• macOS
• Autodesk Flame 2025 or later
• Python 3.13 or higher (python3 --version)
• Node.js v22 or higher (required by Claude Code)
• Claude Code 2.x (npm install -g @anthropic-ai/claude-code)
• A Claude account (claude.ai) — Pro, Max, or API key

Optional — local / free inference with Ollama:

• Ollama >= 0.17.6 installed on your Mac, a Linux GPU server, or both
  • macOS: brew install ollama && brew services start ollama
  • Linux: see https://ollama.com/download/linux (systemd)
  • Verify: ollama --version
• Create the qwen3.5-mcp tag (required — AVAILABLE_MODELS in hooks/flame_mcp_bridge.py expects this exact name):

  ollama pull qwen3.5:9b
  ollama cp qwen3.5:9b qwen3.5-mcp
  

  The bridge forces num_ctx=24576 at runtime via a pre-flight POST to Ollama's native /api/generate endpoint, so a custom Modelfile with PARAMETER num_ctx is not needed — the Anthropic-compat endpoint ignores Modelfile settings anyway. If you want different defaults on num_ctx for some reason, see the advanced Ollama setup below.
• See Ollama setup below for backend options

Note on Python versions: The MCP server runs on your system Python (3.13+). Code executed inside Flame uses Flame's bundled Python interpreter (Flame 2026 ships Python 3.11.5; Flame 2027 ships Python 3.13.3).

---

Installation

Automatic (recommended)

git clone https://github.com/abrahamADSK/flame-mcp.git  # replace with your fork URL if applicable
cd flame-mcp
chmod +x install.sh
./install.sh

The installer will:

1. Create a Python virtual environment
2. Install dependencies (mcp, chromadb, sentence-transformers)
3. Copy the Flame hook to /opt/Autodesk/shared/python/ (requires sudo)
4. Register the MCP server with Claude Code
5. Build the RAG documentation index
6. Generate .claude/settings.local.json with the non-destructive MCP tools pre-approved (39 tools total; destructive tools such as execute_python, the create_*/timeline_* writers and undo_last_operation are left for an interactive permission prompt)

Verify installation

After installing, run the health check to confirm everything is in place:

./install.sh --doctor

This runs a 5-check sweep (MCP registration, bridge symlink, optional .env file, venv importability, RAG index) and prints PASS/FAIL/WARN/SKIP with remediation hints for each check. The bridge-symlink check now sha256-compares the deployed hook against hooks/flame_mcp_bridge.py and FAILs on a stale regular-file copy. Recommended before first use.

Manual

# 1. Clone and set up
git clone https://github.com/abrahamADSK/flame-mcp.git  # replace with your fork URL if applicable
cd flame-mcp

# 2. Virtual environment + dependencies
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt --no-user

# 3. Build the RAG index
python -m flame_mcp.rag.build_index

# 4. Install the Flame hook
sudo cp hooks/flame_mcp_bridge.py /opt/Autodesk/shared/python/

# 5. Register with Claude Code
claude mcp add flame -- "$(pwd)/.venv/bin/python" -m flame_mcp.server

# 6. (Optional) Claude Desktop
#    Copy claude_desktop_config.json to ~/Library/Application Support/Claude/

---

Usage

1. Flame menu — MCP Bridge

When Flame starts, the hook registers an MCP Bridge submenu in Flame's main menu bar:

MCP Bridge  [● Active]
├── Status: ● Active — unix socket  → shows current bridge status
├── Start bridge                   → start Unix socket listener (TCP fallback)
├── Stop bridge                    → stop the listener
├── Restart bridge                 → stop + start
├── Claude Chat  (embedded)        → open Qt chat window inside Flame
├── Launch Claude (terminal)...    → open Claude Code in Terminal.app
├── Reload hook                    → hot-reload the bridge without restarting Flame
├── Connection test                → test the bridge socket round-trip, shows latency
└── View log...                    → open the bridge log file in TextEdit

The status indicator updates every time you open the menu:

• ● Active — bridge is listening, ready to receive commands
• ○ Inactive — bridge is stopped

2. Embedded Claude Chat

Claude Chat (embedded) opens a native Qt window directly inside Flame — no terminal required. Type natural language requests and Claude responds, controlling Flame in real time.

• Runs the claude CLI with your Claude Code session; CLAUDE_PATH (environment or ~/flame-mcp/.env) optionally overrides its location
• Executes Flame code via the Unix socket bridge (thread-safe, non-blocking)
• Uses the local RAG index to look up API patterns before every call
• Requires PySide6 (bundled with Flame 2026+)

Chat commands

In addition to natural language, the chat input accepts these special commands:

Command	Description
/undo	Undo the last Flame action. Triggers flame.execute_shortcut("Undo") directly — bypasses Claude, instant.
/undo N	Undo the last N Flame actions (e.g. /undo 3). After each Claude response the chat shows how many actions were performed, so you know the right N.
/wrong	Tell Claude the last response was incorrect. Injects a correction message into the conversation so Claude re-analyses and tries again without learning the wrong pattern.
/wrong <reason>	Same as /wrong but with context (e.g. /wrong me diste el desktop en vez de la librería). Claude uses the reason to understand exactly what to correct.

Tip: /undo and /wrong can be combined. If Claude deleted something it shouldn't have, type /undo N first to reverse the Flame action, then /wrong <reason> so it doesn't repeat the mistake.

Model selector dropdown — backends defined in hooks/flame_mcp_bridge.py :: AVAILABLE_MODELS, switch without leaving Flame:

Backend	Models available (model IDs in backticks)	Requires	Works offline?
anthropic	Claude Opus 5.5 (claude-opus-5-5, default), Claude Fable 5.1 (claude-fable-5-1), Claude Sonnet 5.5 (claude-sonnet-5-5)	Anthropic API key	✗
ollama	Qwen3.5 9B (qwen3.5-mcp), GLM-4.7 Flash (glm-4.7-flash) ⚠ not recommended — tool-calling broken in Ollama as of June 2026 (issues #13820/#13840)	gpu-server on LAN + GPU, LAN reachable at config.json → ollama_url	✗
ollama_mac 🍎	Qwen3.5 9B (qwen3.5-mcp), Qwen3.5 4B (qwen3.5:4b)	Ollama on Mac (brew install ollama), models pulled locally	✓

Selection is persisted to ~/flame-mcp/config.json between sessions. The combo label shows the server hostname for ollama, or localhost for ollama_mac. Anthropic model IDs are reviewed every 14 days against the Anthropic model catalogue via ~/Projects/.external_versions.yml (enforced by verify_concepts.py).

Configuration precedence (env-var vs config.json)

Two different policies apply depending on what you are configuring:

• Socket transport (FLAME_BRIDGE_SOCKET) — env var wins over any config.json default. Useful for overriding the bridge path in a dev sandbox without touching the committed config.
• Model + backend + ollama_url — config.json wins; there is no env var override. The Flame panel writes the user's choice back to config.json so selection is sticky across restarts.
• claude binary path (CLAUDE_PATH) — env var / .env, not config.json. Optional: without it the bridge searches the usual install locations.

The full precedence table (including fallback chains, defaults, and the asymmetry between transport and model settings) lives in docs/ARCHITECTURE.md §9 and §11.

3. Claude Code (terminal)

cd ~/flame-mcp
source .venv/bin/activate
claude

Then talk naturally:

> List all libraries and reels
> Create a new reel called "MASTER" in Default Library
> Delete all reels named TEST, TEST2 from Default Library
> What's the current project frame rate?

---

MCP Tools (39)

Tool	Description
execute_python	Execute arbitrary Python code inside Flame with full API access
execute_plan	Run a structured JSON plan against Flame (F5b — preferred over execute_python for covered ops)
get_project_info	Return name, frame rate, resolution, bit depth of the active project
list_libraries	List all libraries in the project with reel counts
list_reels	List reels in a library, or across all libraries
list_clips	List clips and sequences (with durations) in a library/reel, or across all libraries
list_desktop_reels	List the full desktop structure: reel groups, reels, and clip names
list_batch_groups	List all batch groups in the active desktop with their reel counts
list_all_projects	List all Flame projects available on this workstation
get_clip_metadata	Get detailed metadata for a specific clip (resolution, frame rate, duration, etc.)
get_selected_clips	Return the clips currently selected in the Flame media panel or desktop
get_source_path	Get the filesystem source path of a clip, reel, or library
collect_media_paths	Collect filesystem paths for all clips in a library or reel
get_write_node_settings	Get the Write File node settings from the current Batch setup
flame_wiretap_tree	Inspect the Wiretap IFFFS node tree at a given path
get_flame_version	Return the running Flame version string
ping	Check whether the bridge to Autodesk Flame is reachable
search_flame_docs	Semantic RAG search over Flame API documentation — call before execute_python
resolve_concept	Fast static lookup: map a user concept to the correct API path and tool
learn_pattern	Add a new working pattern to FLAME_API.md and rebuild the index
session_stats	Show token usage and RAG savings for the current session
reset_session_stats	Zero the session stats counters immediately (idle auto-reset fires after 30 min inactivity)
list_flame_logs	List all log files available in /opt/Autodesk/logs
read_flame_log	Read a Flame log file with optional tail/grep filtering
create_sequence	Create a new empty sequence in a Flame library/reel (optional duration in frames)
render_batch	Render the open Batch Group — or any group by exact name (batch_group argument), without switching the open one (measured Chat 109). Background Reactor by default (Foreground where the workstation has no Reactor); scheduled via idle event
export_clip	Export a clip to disk via a Flame export preset (PyExporter, scheduled via idle event — never deadlocks Flame)
create_library	Create a new library in the active project workspace
create_reel	Create a new reel inside a library
create_folder	Create a new folder inside a library
create_reel_group	Create a new reel group inside a library
create_batch_group	Create a new empty Batch Group on the desktop
import_clips	Import media from disk into a library (or a reel within it)
timeline_insert	Ripple-insert a source clip into a sequence's timeline
timeline_overwrite	Overwrite part of a sequence's timeline with a source clip
rename_segments	Rename a clip (all its segments) in a Flame library/reel
fpt_link	Report the native Flame↔FPT project link (shotgun_project_name attribute). READ-ONLY — set/break were removed in Chat 98 after both in-vivo writes triggered Flame's error report; links are created and broken from Flame's own FPT menu
operation_history	Show the last N execute_python operations recorded this session
undo_last_operation	Undo the last undoable execute_python operation

Visible progress on long operations — the five long-running tools (execute_python, flame_wiretap_tree, render_batch, export_clip, import_clips) stream an MCP ctx.info heartbeat every 10 s while the operation blocks inside Flame, instead of staying silent until done. Fast operations emit nothing. Internally each of these tools is an async wrapper over a sync _<name>_impl body — the execute_plan op registry and the test suite call the sync bodies directly.

Tool workflow

Every Claude response to a Flame request follows this sequence:

search_flame_docs(query)          ← look up correct API patterns
  └─ if score < 60%: warn         ← pattern may not be documented
execute_python(code)              ← run the code in Flame
  └─ if score was < 60% and ok:
       learn_pattern(desc, code)  ← teach the system (self-improvement)
session_stats()                   ← show token summary

---

Skills (2)

Tools are what the server can do. Skills are the recipe — which tools, in what order, and what fails silently. They live in docs/skills/, version controlled with the code they describe, and load only when the request matches their trigger, so they cost almost nothing until they are relevant.

Skill	Fires on
flame-batch-authoring	Any flame.batch call, reads included: the main-thread idle-event contract, the active group that cannot be switched from Python, node-name scoping
flame-delivery	Render → export → review Version → open clip: export deadlocks, a start frame that moves with the current version, presets that apply no colour

Activate them on a fresh clone by symlinking into your user skills directory:

for s in flame-batch-authoring flame-delivery; do
  ln -s "$PWD/docs/skills/$s" ~/.claude/skills/"$s"
done

flame-delivery keeps Flame truth, tk-flame Toolkit behaviour and this facility only in separate sections, so a local configuration accident is never read as product behaviour. See docs/skills/README.md for the four-layer split (tool / skill / RAG / memory).

Self-improving RAG

The system maintains a local semantic search index (rag/index/) built from all documents in the docs/ folder plus FLAME_API.md. Before every execute_python call, Claude searches this index to find the correct API pattern — avoiding guesswork and saving tokens.

Knowledge base (≈800 chunks across 14 documents)

File	Chunks	Content
FLAME_API.md	~295	Core Flame Python API — PyClip, PyReel, PyBatch, PyLibrary, connectors, markers, PyTime, import/export code samples. Auto-extended by learn_pattern.
flame_advanced_api.md	~78	Action node (PyActionNode, output types, FBX import), Color Management (CDL/LUT/CTF), Exporter (safe schedule_idle_event pattern), MediaHub, Conform/AAF workflow, Timeline FX/BFX, Python hooks reference.
flame_segment_timeline_api.md	~61	Full PySegment API (trim, slip, create_effect, connected_segments), corrected PyClip.render() signature, PyBatch.create_batch_group(), PySequence methods, post-conform batch group creation patterns.
flame_code_samples.md	~46	Extracted Autodesk official zip samples — clip ops, render, Timeline FX wiring, Action compass nodes.
flame_youtube_patterns.md	~60	Patterns extracted from Logik-TV / YouTube tutorials (OCR + transcript mining).
flame_community_workflows.md	~23	Logik Forum operator terminology → API mapping. Conform jargon, batch compositing terms, render/delivery slang.
flame_cookbook_official.md	~22	Official Autodesk Python API code samples.
flame_reference_guide.md	~30	Troubleshooting + env-setup reference.
flame_ocr_patterns.md	~15	OCR-extracted patterns (v1 pipeline).
flame_ocr_patterns_v2.md	~23	OCR-extracted patterns (v2 pipeline).
flame_openclip_patterns.md	~8	OpenCLIP pattern extractor outputs.
flame_vocabulary.md	~8	Flame-specific terminology glossary — operators vs. the Python API names.
wiretap_sdk_python_reference.md	~76	Wiretap Python SDK — low-level bridge from flame module to the Wiretap server.
wiretap_cli_reference.md	~38	Wiretap command-line reference — wiretap_print_tree, wiretap_duplicate_node, etc.

How it learns (3-level system)

1. search_flame_docs returns the max relevance score of the best match
2. If score < 60%, the pattern is not well-documented — Claude is warned
3. After a successful execute_python, Claude calls learn_pattern(description, code)
4. Outcome depends on the active model's trust level:
   • Write-trusted model (Opus / Fable) → appended to FLAME_API.md, index rebuilt in background
   • Sonnet (the default cloud model) is not write-trusted → its proposals are staged to rag/candidates.json for human review, same as the read-only local models
   • Read-only model (Qwen, Llama…) → staged in rag/candidates.json for human review
5. On failed execution with low RAG score → logged to rag/failed.json as a knowledge gap
6. Next session, verified patterns return >70% relevance instantly

Manually rebuild the index

cd ~/flame-mcp
source .venv/bin/activate
python -m flame_mcp.rag.build_index

RAG log

Every search query, its results, and relevance scores are logged to:

logs/flame_rag.log

---

Token tracking

Every tool call appends a compact stats footer:

─────────────────────────────
🔍 RAG · max relevance 72% · ~210 tokens · ~1290 avoided vs full doc
📊 Session · 3 exec · 2 RAG
   Tokens used             : ~640  🟢 low
   Avoided by RAG/tools    : ~2580  (80% of context)

Ratings:

• 🟢 low — under 100 tokens for the call
• 🟡 medium — 100–400 tokens
• 🔴 high — over 400 tokens

session_stats() gives the full session breakdown including how many patterns were auto-learned (🧠 self-improved!).

Note: Token cost warnings (🟡 🔴) are only shown when using Anthropic cloud models. For Ollama backends (local or cloud) they are suppressed — there are no rate limits or token costs involved.

---

Project structure

flame-mcp/
├── src/flame_mcp/server.py     # MCP server — runs on macOS, talks to Claude
├── hooks/
│   └── flame_mcp_bridge.py    # Flame hook — Unix socket bridge + Qt chat widget
├── src/flame_mcp/rag/
│   ├── build_index.py         # Build / rebuild the ChromaDB index
│   └── search.py              # Semantic search, returns (text, max_score)
├── rag/
│   ├── corpus.json            # Chunked corpus (BM25 source, git-tracked)
│   └── index/                 # ChromaDB vector store (git-ignored)
├── docs/skills/               # Claude Code skills (symlinked into ~/.claude/skills/)
│   ├── flame-batch-authoring/ # Batch/BFX graph authoring contract
│   └── flame-delivery/        # Render → export → review Version → open clip
├── FLAME_API.md               # Flame Python API reference + patterns (RAG source)
├── CLAUDE.md                  # Instructions for Claude Code terminal context
├── claude_desktop_config.json # Claude Desktop MCP config (copy to ~/Library/...)
├── requirements.txt
├── install.sh
├── LICENSE
├── logs/
│   ├── flame_mcp_bridge.log   # bridge activity log
│   └── flame_rag.log          # RAG query log with relevance scores
└── docs/
    ├── flame-mcp-reference.pdf      # Full reference guide
    ├── FLAME_API.md                 # (root) Core API + self-learned patterns
    ├── flame_advanced_api.md        # Action, Color Mgmt, Exporter, Conform, TL FX
    ├── flame_segment_timeline_api.md# PySegment, PyClip.render, PyBatch.create_batch_group
    ├── flame_community_workflows.md # Logik Forum operator jargon → API
    ├── flame_cookbook_official.md   # Official Autodesk Python code samples
    └── flame_vocabulary.md          # Operator terminology glossary

---

Ollama setup (optional)

Three Ollama-based backends are available, covering every scenario:

┌─────────────────┬──────────────────────┬────────────────────────────────────┐
│ Backend         │ Physical path        │ Use case                           │
├─────────────────┼──────────────────────┼────────────────────────────────────┤
│ ollama          │ Mac → gpu-server LAN │ Best quality, big GPU model        │
│ ollama_cloud ☁  │ Mac localhost → ☁    │ Anywhere with internet, no GPU     │
│ ollama_mac  🍎  │ Mac localhost        │ Offline emergency, no internet     │
└─────────────────┴──────────────────────┴────────────────────────────────────┘

ollama_cloud and ollama_mac both require Ollama installed on the Mac — a lightweight daemon (~50 MB, no models bundled) that listens at localhost:11434 and implements the Anthropic Messages API. For cloud models it acts as a transparent proxy to ollama.com; for local models it runs them directly using Mac CPU/GPU.

Ollama was not previously required on the Mac — it only ran on gpu-server. This is a new requirement for the two Mac-based backends.

Option 1 — Self-hosted GPU (ollama backend)

Best quality. Runs on the Linux workstation (gpu-server) with a dedicated GPU.

On the Linux machine (gpu-server):

# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh

# Allow remote connections and keep models warm
sudo systemctl edit ollama --force --full
# Add under [Service]:
#   Environment="OLLAMA_HOST=0.0.0.0:11434"
#   Environment="OLLAMA_KEEP_ALIVE=10m"
#   Environment="OLLAMA_NEW_ENGINE=true"
sudo systemctl restart ollama

# Pull the models defined in AVAILABLE_MODELS (hooks/flame_mcp_bridge.py)
ollama pull qwen3.5:9b
ollama cp qwen3.5:9b qwen3.5-mcp          # matches the `qwen3.5-mcp` tag
# NOTE: glm-4.7-flash is NOT recommended — tool-calling broken in Ollama
# (upstream issues #13820/#13840, as of June 2026; real download size ~19 GB q4).
# The model remains in AVAILABLE_MODELS for existing users. Prefer qwen3.5-mcp.
ollama pull glm-4.7-flash                  # matches the `glm-4.7-flash` tag

In the Flame widget:

1. Select Qwen3.5 9B 🖥 from the model dropdown (GLM-4.7 Flash is not recommended — see note above)
2. Enter the server URL (e.g. http://192.168.1.50:11434) and press Enter
3. The combo label updates to show · gpu-server confirming the server is saved

GPU requirements: Qwen3.5 9B (~6.6 GB Q4_K_M) needs ~8+ GB VRAM with num_ctx=24576 set at runtime by the bridge. The bridge pre-flight overrides Modelfile num_ctx on every session (Ollama's Anthropic-compat endpoint ignores it otherwise). GLM-4.7 Flash (~19 GB q4) requires at least ~20 GB VRAM and is NOT recommended due to tool-calling bugs in Ollama (issues #13820/#13840).

Option 2 — Ollama cloud proxy (ollama_cloud backend)

Free 480B parameter model running on ollama.com's infrastructure. Works anywhere with internet, no GPU required. Requires Ollama on the Mac.

On the Mac (one-time setup):

brew install ollama
# Start the daemon (add to login items if you want it always running)
ollama serve

In the Flame widget:

1. Select qwen3-coder 480B ☁ from the model dropdown
2. The combo shows · localhost → ☁ — no further configuration needed
3. On first use the model tag qwen3-coder:480b-cloud is downloaded automatically

The Mac daemon forwards the request to ollama.com's servers. Authentication with ollama.com is handled by the daemon using your logged-in account — no API key needed in the widget.

To log in to ollama.com from the Mac: ollama login in Terminal.

Option 3 — Mac offline fallback (ollama_mac backend)

Small model stored locally on the Mac. Works with no internet and no gpu-server — useful when working remotely on a laptop.

On the Mac (one-time setup, ~3 GB download):

brew install ollama
ollama serve
ollama pull qwen3.5:4b

In the Flame widget:

1. Select Qwen3.5 4B 🍎 from the model dropdown
2. The combo shows · localhost — ready to use offline

The 4B tag (qwen3.5:4b) is pulled directly — no ollama cp alias needed. The larger Qwen3.5 9B 🍎 option (qwen3.5-mcp) requires ollama pull qwen3.5:9b && ollama cp qwen3.5:9b qwen3.5-mcp first. Both IDs are the offline (ollama_mac) entries in the bridge's AVAILABLE_MODELS.

Quality is significantly lower than the 30B or 480B models. Runs on Mac CPU (no GPU required); response time is slower than GPU backends.

⚠️ Tool use limitation: small (4B–9B) models often fail to invoke MCP tools correctly — they may print raw JSON instead of executing the tool call. This backend is best suited for text queries (API questions, code explanations) rather than live Flame control. For actual Flame operations use anthropic, ollama, or ollama_cloud.

How the backends work internally

Ollama implements the Anthropic Messages API natively (v0.14+). The bridge sets ANTHROPIC_BASE_URL before launching the claude CLI subprocess:

• ollama → http://<ollama_url> (gpu-server LAN address)
• ollama_cloud → http://localhost:11434 (Mac daemon → cloud proxy)
• ollama_mac → http://localhost:11434 (Mac daemon → local model)

For the ollama (LAN GPU) backend only, the bridge also sends a pre-flight request to Ollama's native /api/generate endpoint to force-load the model with the correct context window. This is necessary because Ollama's Anthropic-compatible endpoint ignores the num_ctx set in a Modelfile.

---

Flame hook locations

Flame loads Python hooks at startup from these paths (in order of priority):

Path	Scope
$DL_PYTHON_HOOK_PATH	Custom environment variable
/opt/Autodesk/shared/python/	All installed Flame versions
/opt/Autodesk/<version>/python/	Specific Flame version
/opt/Autodesk/user/<username>/python/	Specific system user

This project uses /opt/Autodesk/shared/python/ so the bridge works across all Flame versions.

---

Troubleshooting

Claude can't connect to Flame

• Make sure Flame is open
• Check MCP Bridge → Status in the Flame menu
• Verify flame_mcp_bridge.py is in /opt/Autodesk/shared/python/
• Check the Unix socket exists: ls -la ~/flame-mcp/run/flame_mcp.sock — should be srw-------
• If the socket is absent the bridge is not running: there is no TCP fallback. Check Flame's console for the [FlameMCPBridge] Active on … line

Low RAG relevance scores on common operations

• If a pattern scores < 60%, Claude will auto-learn it after a successful run
• You can also manually rebuild the index: python -m flame_mcp.rag.build_index

Claude Chat (embedded) doesn't open

• Check logs/flame_mcp_bridge.log for error details
• Ensure the claude CLI is installed and signed in; if it is not found, set CLAUDE_PATH in your environment or in ~/flame-mcp/.env
• Flame 2026+ uses PySide6; older versions use PySide2 (both supported)

Ollama model runs on CPU instead of GPU

• Check journalctl -u ollama -n 50 for library=cpu or offloaded 0/N layers
• Ensure CUDA is initialised: python3 -c "import ctypes; print(ctypes.CDLL('libcuda.so.1').cuInit(0))" — should return 0; if 999, reboot the Linux machine
• Add Ollama's CUDA libs to ldconfig: create /etc/ld.so.conf.d/ollama-cuda.conf with /usr/local/lib/ollama/cuda_v12 and run sudo ldconfig
• Set OLLAMA_NEW_ENGINE=true in the systemd override

Ollama model truncates context (truncating input prompt: limit=4096)

• The Anthropic-compatible endpoint ignores Modelfile num_ctx — this is expected
• The bridge fixes it automatically via a pre-flight /api/generate request; check the bridge log for Ollama pre-load OK
• If the issue persists, verify the Modelfile has PARAMETER num_ctx 24576 and the model was created with ollama create

Ollama cloud / mac-local: "Ollama not found on this Mac"

• Install and start the Mac daemon: brew install ollama && ollama serve
• Verify it's running: curl http://localhost:11434/api/version
• For ollama_mac only, also pull the model: ollama pull qwen2.5-coder:7b
• For ollama_cloud, log in so the daemon can authenticate: ollama login

Ollama cloud model not responding

• The 480B model may take 2–5 minutes on first inference — the widget has a 5-minute watchdog
• Check daemon logs: journalctl --user -u ollama (Linux) or ollama serve output (Mac)

The bridge will not start The bridge binds a UNIX domain socket and has no fallback transport — if the bind fails it says so on Flame's console and stops, rather than degrading to a transport with no access control. Override the path with FLAME_BRIDGE_SOCKET=/path/to/custom.sock; keep it short, since sun_path is capped near 104 bytes.

pip install fails with --user conflict Add --no-user to pip commands. Happens when install.user = true is set globally.

---

Compatibility

Flame version	Internal Python	Qt	Status
2023	3.9.7	PySide2	✓ Compatible
2024	3.9.x	PySide2	✓ Compatible
2025	3.11.x	PySide2	✓ Compatible
2026	3.11.5	PySide6	✓ Tested
2027	3.13.3	PySide6	✓ Tested

---

Ecosystem

flame-mcp is part of a four-component VFX pipeline. Each component has a defined role:

Repo	Role
flame-mcp	Controls Autodesk Flame for compositing, conform, and finishing
maya-mcp	Controls Autodesk Maya for 3D modeling, animation, and rendering
fpt-mcp	Connects to Autodesk Flow Production Tracking (ShotGrid) for production tracking, asset management, and publishes
vision3d	GPU inference server for AI-powered 3D generation — the remote backend for maya-mcp's image-to-3D and text-to-3D tools

flame-mcp operates at the finishing stage of the pipeline. When both fpt-mcp and flame-mcp are active, Claude can query ShotGrid for shot status, resolve the correct media path, and execute Flame operations against it in a single conversation. maya-mcp can hand off rendered outputs that flame-mcp then picks up for conform and grade. vision3d is not directly consumed by flame-mcp.

---

License

MIT