# Flame Mcp

> MCP server for Autodesk Flame — clip control, timelines, and effects with RAG search, anti-hallucination safety, and self-learning

- **Type:** MCP server
- **Install:** `agentstack add mcp-abrahamadsk-flame-mcp`
- **Verified:** Pending review
- **Seller:** [abrahamADSK](https://agentstack.voostack.com/s/abrahamadsk)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [abrahamADSK](https://github.com/abrahamADSK)
- **Source:** https://github.com/abrahamADSK/flame-mcp

## Install

```sh
agentstack add mcp-abrahamadsk-flame-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](https://claude.com/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](https://github.com/safishamsi/graphify) and deployed to GitHub Pages on every push to `src/`:

**[abrahamadsk.github.io/flame-mcp](https://abrahamadsk.github.io/flame-mcp/)** · part of the [MCP ecosystem graph hub](https://abrahamadsk.github.io/mcp-graphs/).

`flame-mcp` connects [Claude](https://claude.ai) to [Autodesk Flame](https://www.autodesk.com/products/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](https://www.autodesk.com/products/flame) 2025 or later
- Python 3.13 or higher (`python3 --version`)
- [Node.js](https://nodejs.org) v22 or higher (required by Claude Code)
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview) 2.x (`npm install -g @anthropic-ai/claude-code`)
- A Claude account ([claude.ai](https://claude.ai)) — Pro, Max, or API key

**Optional — local / free inference with Ollama:**
- [Ollama](https://ollama.com) >= 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 `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](#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)

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

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

```bash
# 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](https://docs.anthropic.com/claude/docs/models-overview) 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)

```bash
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 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 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 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 `__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](https://github.com/abrahamADSK)
- **Source:** [abrahamADSK/flame-mcp](https://github.com/abrahamADSK/flame-mcp)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** yes
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-abrahamadsk-flame-mcp
- Seller: https://agentstack.voostack.com/s/abrahamadsk
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.