Skip to main content
Glama

Figma Cache MCP

A local MCP server that caches Figma design data once and then serves it from disk, so an AI agent can read designs without spending any extra Figma API requests. Ships with a web management panel for cache status, quota usage and syncs.

The point: iterate with an agent without burning through a limited monthly Figma request quota.

Features

  • Whole-file cache: design tree with path geometry (geometry=paths), file name, components and styles

  • Icon SVG cache: multi-vector icons are exported as one complete SVG; requesting any inner vector id still returns the full icon. Content-identical exports are deduplicated to keep request counts low

  • Image fills: image bytes are downloaded to disk and served by local path. Temporary Figma links are refreshed only when needed, with a 60-second cooldown and Retry-After handling

  • Safe cache-miss behaviour: if a node is not cached, no request is sent to Figma — only an error is returned

  • Quota accounting: per-tier (Tier 1 / Tier 2) counters, a 50-entry history, and a --dry-run mode that shows the cost of an operation before it runs

  • Multiple tokens: stored in ~/.config/figma-cache-mcp/tokens.json with mode 600; values are never returned to the browser

  • Zero-cost browsing: the panel reads local files only, so checking status never spends quota

Related MCP server: filesystem-mcp

Requirements

  • Linux, WSL, or macOS. Native Windows is not supported: the code uses fcntl for file locking.

  • Python 3.10 or newer

  • A Figma personal access token: Figma → Settings → Security → Personal access tokens

Install

git clone https://github.com/abotalebie/Figma-Cache-MCP.git figma-cache-mcp
cd figma-cache-mcp
./setup.sh

setup.sh creates the .venv virtualenv, installs dependencies and marks the shell scripts executable. Manual install:

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
chmod +x run-mcp.sh run-panel.sh

Run the panel

./run-panel.sh              # default: http://127.0.0.1:8765
./run-panel.sh --port 9000

The panel binds to 127.0.0.1 by default. Add a token under Stored tokens or set the FIGMA_TOKEN environment variable.

Action

What it does

Cost

Cache whole file

full tree + SVGs + image links

2× Tier 1, 1× Tier 2

Cache a frame

JSON for that frame only

1× Tier 1

Retry SVGs

reuses the cached tree; requests only if needed

usually 0 or 1× Tier 1

Retry images

reuses fresh links

usually 0 or 1× Tier 2

Downloading SVG and image files from the Figma CDN does not consume API quota.

Connect a client (MCP)

The server uses the stdio transport: the client launches it, so there is no need to run it by hand.

Client on the same machine (Linux/macOS):

{
  "mcpServers": {
    "figma-cache": {
      "command": "/absolute/path/to/figma-cache-mcp/run-mcp.sh"
    }
  }
}

Client on Windows, server inside WSL:

{
  "mcpServers": {
    "figma-cache": {
      "command": "wsl.exe",
      "args": ["-d", "Ubuntu", "--", "/home/USER/figma-cache-mcp/run-mcp.sh"]
    }
  }
}

Where to put it:

  • Claude Desktop: Settings → Developer → Edit Config → claude_desktop_config.json

  • Cursor: Settings → MCP → Add Server → mcp.json

  • Other clients: anything that supports MCP over stdio

The token comes from ~/.config/figma-cache-mcp/token (read by run-mcp.sh) or the FIGMA_TOKEN environment variable. Without a token the server still works fully offline and serves local images; only image-link refresh is disabled.

MCP tools

get_cached_design(url)

Takes a Figma Copy link to selection URL (must contain node-id) and returns that node's JSON from cache: layout (absoluteBoundingBox), colors (fills/strokes), text and typography, component structure and fillGeometry. Nodes with a ready SVG are marked svg_cached: true.

get_cached_svg(file_key, node_id)

Reads a complete icon SVG from cache. The instance id, its frame, its group, or any inner vector id all return the same complete SVG.

Quota guide

  • Caching a whole file: 2 Tier 1 requests (tree + SVG export) and 1 Tier 2 request (image links)

  • Caching one frame: 1 Tier 1 request

  • sync-file.py --dry-run FILE_KEY reports the request cost without spending quota

  • If the ids do not fit in one SVG request, the script stops; pass --max-image-requests=N to allow more spend

  • On HTTP 429 the Retry-After value is respected and the cache is left untouched

Suggested agent prompt

You have access to a local cached Figma MCP server named "figma-cache". Use it for all Figma design data. NEVER call api.figma.com or the live Figma API yourself - the account has a strict monthly request quota.

1. For any Figma selection URL (must contain node-id), call get_cached_design(url).
2. On a cache miss, do not retry and do not fetch from Figma. Ask the user to sync that file or frame in the cache panel.
3. Nodes with "svg_cached": true have a ready SVG: call get_cached_svg(file_key, node_id). Multi-vector icons return as one complete SVG.
4. For image fills, use status "cached_local" and the local path. Never guess image content.
5. Build the UI from the JSON. For vectors without SVG, use fillGeometry path data if present.
6. When you need another node, ask the user for its "Copy link to selection" URL instead of guessing ids.

Project layout

File

Role

server.py

MCP server exposing get_cached_design and get_cached_svg

panel.py

Local web panel (HTTP on localhost), token management, job runner

sync.py

Caches one or more specific nodes via GET /v1/files/:key/nodes

sync-file.py

Caches the whole file, icon SVGs and images; supports --dry-run, --svg-only, --images-only

tokens.py

Token storage with mode 600

usage.py

Tier-aware request counters and history

run-mcp.sh / run-panel.sh

Launch the server or panel from .venv

setup.sh

Creates the virtualenv and installs dependencies

cache/

Local cache (git-ignored)

Privacy and security

  • Tokens live in ~/.config/figma-cache-mcp/tokens.json with mode 600 and are never sent to the browser; they are only injected into the sync process

  • The panel binds to 127.0.0.1 by default. Do not expose it on 0.0.0.0 — it has no authentication

  • /svg/ and /img/ paths are validated with regexes and parent-directory checks to prevent path traversal

  • The cache/ directory holds your design data; it is listed in .gitignore and must not be published

Contributing

  1. Fork the repository

  2. Create a branch: git checkout -b feature/name

  3. Commit your changes

  4. Open a pull request

For behavioural changes, please open an issue first describing the quota impact.

License

Released under the MIT License — 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
      D
      maintenance
      Enables AI agents with long-term memory and retrieval-augmented generation (RAG) capabilities, allowing them to recall past conversations, search local files, and learn user preferences.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables agents to read large files, logs, and web pages without filling their context by saving full text locally, returning previews, and searching stored content for specific passages. It also helps preserve session continuity after compaction by tracking edited files and open tasks.
      1
      MIT