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 (falls back to TCP port 4444 if AF_UNIX is unavailable). It receives Python code, executes it inside Flame's Python interpreter with full access to the flame module, and returns the result.

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): ``bash ollama pull qwen3.5:9b ollama cp qwen3.5:9b qwen3.5-mcp ` The bridge forces numctx=24576 at runtime via a pre-flight POST to Ollama's native /api/generate endpoint, so a custom Modelfile with PARAMETER numctx 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](#ollama-setup-optional) 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 (38 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, .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 TCP 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.

• Reads ANTHROPIC_API_KEY from environment or ~/flame-mcp/.env
• 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 | 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 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 Fable 5 (claude-fable-5), Claude Opus 4.8 (claude-opus-4-8), Claude Sonnet 4.6 (claude-sonnet-4-6) | 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, FLAME_BRIDGE_PORT) — 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.
• Anthropic credentials (ANTHROPIC_API_KEY) — env var / .env, not config.json.

The full precedence table (including fallback chains, defaults, and the asymmetry between transport and model settings) lives in [docs/ARCHITECTURE.md §9](docs/ARCHITECTURE.md) 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 (38)

| 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 executepython 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 executepython | | resolve_concept | Fast static lookup: map a user concept to the correct API path and tool | | learn_pattern | Add a new working pattern to FLAMEAPI.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 current Batch Group (Background Reactor by default; scheduled via idle event — never blocks Flame) | | 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 | | operation_history | Show the last N executepython 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 __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 70% relevance instantly

### Manually rebuild the index

```bash
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.

---

##

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: abrahamADSK
• Source: abrahamADSK/flame-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.