Figma Cost Optimizer Bridge

Figma Cost Optimizer Bridge is a local MCP server that turns Figma Desktop design context into compact, implementation-ready web handoffs for LLM coding agents.

It sits between an MCP client and the local Figma Desktop MCP endpoint. Instead of forwarding raw get_design_context output full of metadata, absolute coordinates, repeated class strings, and inline SVG, the bridge returns a smaller Markdown handoff with cleaned JSX intermediate skeleton code, design tokens, reusable repeated structures, and a screenshot path. The handoff can target React, Vue, Svelte, or HTML, with Tailwind, styled-components, Emotion, CSS Modules, or inline styles.

The result is lower input-token cost and less context noise while still preserving the information a coding agent needs to build the UI accurately.

Benchmark Snapshot

Latest reproducible fixture: DashStack Dashboard, Figma node 2791-32584, measured on 2026-06-16 with a blind 3-run benchmark (anthropic / claude-sonnet-4-6, temperature 0, one compile-only repair).

| Path | Input chars | Est. text tokens | Image tokens | Total est. tokens | Pixel similarity (mean) | |---|---:|---:|---:|---:|---:| | Official Figma MCP raw | 51,543 | 12,886 | 1,040 | 13,926 | 83.12% | | Bridge handoff | 28,928 | 7,232 | 0 | 7,232 | 84.76% |

Estimated input-token saving: 48.07%, while the bridge arm was +1.65 pp more similar to the reference on average — nearly half the input tokens with no loss of visual accuracy. See the full report in docs/BENCHMARK_RESULTS.md.

Features

• Token-efficient handoffs: removes or compresses noisy Figma metadata, absolute positioning, repeated Tailwind tokens, data-* attributes, and inline SVG blocks.
• Screenshot path mode: saves the screenshot locally and returns its absolute path instead of inlining image data by default.
• Repeated subtree dedupe: converts repeated JSX structures into one component definition plus instance data.
• Shared class extraction: keeps class tokens shared by all instances in the component template and only passes differences as props.
• Default prop values: promotes common slot values to component defaults so repeated instances can omit them.
• Hash cache: reuses previous handoffs when the raw Figma response has not changed.
• Diff handoff: returns only changed lines for previously seen components, with automatic fallback to full handoff when the diff is too large.
• Local component registry: records extracted or scanned project components and suggests reuse in later handoffs.
• Target profiles: generates profile-specific guidance for React, Vue, Svelte, and HTML, plus Tailwind, styled-components, Emotion, CSS Modules, and inline styling.
• Required Ollama pre-analysis: uses local Ollama for color, text, and summary analysis. The MCP server prepares Ollama on startup, and handoff generation fails if analysis cannot run.
• Benchmark harness: measures raw vs bridge input tokens, renders outputs in Playwright, and computes pixel similarity with pixelmatch.

Install

Install from npm:

npm install -g decrease-token-figma
figma-bridge

Install directly from GitHub:

npm install -g github:junseo2323/decrease-token-figma
figma-bridge

For local development:

git clone https://github.com/junseo2323/decrease-token-figma.git
cd decrease-token-figma
npm install
npm run build
npm link
figma-bridge

Ollama is prepared automatically when figma-bridge starts. To prepare it manually:

npm run setup

MCP Client Configuration

Use this configuration in Claude Desktop, Codex, Cursor, or another MCP client:

{
  "mcpServers": {
    "figma-cost-optimizer-bridge": {
      "command": "npx",
      "args": ["-y", "decrease-token-figma"],
      "env": {
        "FIGMA_BRIDGE_ROOT": "/absolute/path/to/your/app"
      }
    }
  }
}

To run the GitHub version directly:

{
  "mcpServers": {
    "figma-cost-optimizer-bridge": {
      "command": "npx",
      "args": ["-y", "github:junseo2323/decrease-token-figma"],
      "env": {
        "FIGMA_BRIDGE_ROOT": "/absolute/path/to/your/app"
      }
    }
  }
}

Codex CLI

From the app project you want the bridge to write assets/cache into:

codex mcp add figma-cost-optimizer-bridge \
  --env FIGMA_BRIDGE_ROOT="$PWD" \
  -- npx -y decrease-token-figma

codex mcp list

To remove it later:

codex mcp remove figma-cost-optimizer-bridge

Claude Code

From the app project you want the bridge to write assets/cache into:

claude mcp add -s local figma-cost-optimizer-bridge \
  -e FIGMA_BRIDGE_ROOT="$PWD" \
  -- npx -y decrease-token-figma

claude mcp list

To remove it later:

claude mcp remove figma-cost-optimizer-bridge

After setup, keep Figma Desktop running with local MCP enabled, select a node, then ask Codex or Claude Code to call get_optimized_figma_handoff.

Avoiding Official Figma MCP Tool Conflicts

Do not register the official figma-mcp server alongside this bridge. If both tools are available, an LLM may choose the raw official get_design_context tool before the optimized bridge handoff.

Use the built-in doctor and migration helper:

figma-bridge doctor
figma-bridge migrate-config --yes

doctor inspects known Claude Desktop, Cursor, workspace MCP, and Codex config locations. migrate-config --yes backs up JSON configs, removes competing official Figma MCP entries, and ensures figma-cost-optimizer-bridge is the Figma MCP server in that config. Codex TOML configs are reported but not rewritten automatically; remove official Figma MCP entries there with the Codex CLI.

When the bridge starts, it also ensures AGENTS.md and CLAUDE.md exist in FIGMA_BRIDGE_ROOT and prepends this guardrail as the first line:

IMPORTANT: For Figma design-to-code work, use only the `figma-cost-optimizer-bridge` MCP server. Do not use or fall back to the official Figma MCP / `figma-mcp` directly.

Set FIGMA_BRIDGE_WRITE_AGENT_RULES=0 if you do not want the bridge to update those files.

Requirements

• Figma Desktop is running.
• Figma's local MCP endpoint is available on 127.0.0.1:3845.
• A Figma node is selected before requesting a handoff.
• FIGMA_BRIDGE_ROOT or the tool argument projectRoot points to the local app project.

MCP Tools

get_optimized_figma_handoff

Fetches the selected Figma node and returns an optimized Markdown handoff plus screenshot information.

| Argument | Values | Default | Description | |---|---|---|---| | projectRoot | absolute path | FIGMA_BRIDGE_ROOT or cwd | Project root for assets and cache | | screenshot | path / inline / none | path | path stores the PNG in cache and returns only its absolute path. inline is for clients without filesystem access | | mode | auto / full / diff | auto | Return a diff when a previous version exists, otherwise a full handoff | | force_refresh | boolean | false | Ignore the cache and capture again even if the raw hash matches | | target | react / vue / svelte / html | react | Target web framework for handoff instructions and code fence | | styling | tailwind / styled-components / emotion / css-modules / inline | tailwind | Styling system for token conversion guidance |

Compatibility aliases

The bridge also exposes get_design_context and get_figma_context as optimized handoff aliases. These names are intentionally compatible with common Figma MCP workflows, but they return bridge handoff Markdown rather than raw official Figma context.

Escape hatches:

• get_raw_figma_context: returns raw Figma selected-node context.
• get_screenshot / get_figma_screenshot: pass-through screenshot helpers.

sync_component_registry

Scans <projectRoot>/src/components using the target profile's component extensions and updates the local component registry. React scans .tsx/.jsx, Vue scans .vue, Svelte scans .svelte, and HTML scans .html. Later handoffs can use this registry to recommend or enforce component reuse.

Workflow

1. Select a node in Figma Desktop.
2. The LLM calls get_optimized_figma_handoff.
3. The bridge fetches raw design context and a screenshot from the local Figma MCP endpoint.
4. Image assets are written to src/assets or the configured asset directory.
5. Raw TSX is cleaned, repeated structures are deduped, and required Ollama analysis is added.
6. The LLM implements the UI from the handoff Markdown and screenshot.

Cache Layout

.figma_cache/
  nodes/ChatScreen_a3f29c01/
    raw.txt
    handoff.md
    diff.md
    screenshot.png
    meta.json
  registry.json

• Unchanged raw responses reuse cached handoffs.
• The two latest versions per component are retained.
• mode: auto creates a diff handoff when a previous version is available.

Environment Variables

| Variable | Description | |---|---| | FIGMA_BRIDGE_ROOT | Project root for assets and cache | | FIGMA_BRIDGE_CACHE_DIR | Override cache directory | | FIGMA_BRIDGE_ASSET_DIR | Override image asset directory | | FIGMA_BRIDGE_WRITE_AGENT_RULES=0 | Disable automatic AGENTS.md and CLAUDE.md guardrail updates | | OLLAMA_BIN | Path to a specific Ollama binary | | FIGMA_BRIDGE_OLLAMA_MODEL | Ollama model to use. Default: llama3.2 | | FIGMA_BRIDGE_OLLAMA_AUTO_INSTALL=0 | Disable runtime Ollama auto-install | | FIGMA_BRIDGE_OLLAMA_AUTO_PULL=0 | Disable runtime model download |

npm Scripts

npm run build              # TypeScript build
npm test                   # Unit tests
npm run setup              # Install/start Ollama and pull the default model
npm run measure            # Estimate token size for .figma_cache/handoff.md
npm run benchmark:capture  # Capture a Figma benchmark fixture
npm run benchmark:tokens   # Measure raw vs bridge input tokens
npm run benchmark:diff     # Render with Vite and compute pixel diff
npm run benchmark:blind    # Run blind multi-run LLM benchmark
npm run benchmark:summary  # Rebuild blind benchmark summary

Reproduce The Benchmark

npm install
npm run build
npx playwright install chromium

# Keep Figma Desktop open, enable local MCP on port 3845,
# and select the target node before capturing.
npm run benchmark:capture -- dashstack-dashboard 2791-32584 WlvYAu5ONnUe7kVcDtmuqk
npm run benchmark:tokens -- dashstack-dashboard
npm run benchmark:diff -- dashstack-dashboard

Artifacts are written to:

benchmarks/fixtures/<slug>/
benchmarks/results/<slug>/

For a stricter comparison, run the blind benchmark with the same model, temperature, screenshot input, output contract, and compile-repair policy while changing only the text input:

export ANTHROPIC_API_KEY=...

npm run benchmark:blind -- dashstack-dashboard \
  --provider anthropic \
  --model claude-sonnet-4-5-20250929 \
  --runs 5 \
  --temperature 0 \
  --max-repairs 1 \
  --experiment-id sonnet45-t0-r5

Runtime Model

This project is not meant to run primarily as a hosted web service. The bridge must access the user's local Figma Desktop selection, local filesystem, and local Ollama server. Use npm or GitHub installation for the actual runtime, and use GitHub Pages for documentation and benchmark reports.

Documentation:

• English Pages: https://junseo2323.github.io/decrease-token-figma/
• Korean Pages: https://junseo2323.github.io/decrease-token-figma/index.ko.html
• Benchmark report: https://junseo2323.github.io/decrease-token-figma/BENCHMARK_RESULTS.html

LLM Implementation Guidelines

• Use the screenshot to decide visual layout, spacing rhythm, and alignment.
• Use the handoff code for exact text, colors, font weights, and design tokens.
• Rename mechanically extracted asset variables to semantic names when implementing.
• Replace inline SVG placeholders with icon components such as lucide-react when possible.

License

MIT