FigJam Context MCP

A local MCP server that turns FigJam boards into source-cited context for LLMs. It reads a board through the Figma REST API, groups stickies, tables, images and arrows into clusters, and answers questions with links back to the original nodes.

GitHub

Documentation

figjam-context-mcp

Real run: ingest_board reads the demo board, answer_from_board cites two conflicting pilot dates, Figma's MCP server edits the board, ingest_board reports the change, diff_board names the edited sticky and table cell, answer_from_board gives the new date

Rendered from the tool calls and outputs of a real run against the public demo board with figjam-context-mcp 0.10.2 and openai/gpt-4.1-mini. Figma's MCP server (use_figma) made the edit.

Why

Workshop boards hold research notes, decisions and open questions, but an LLM cannot read a canvas. Screenshots and PDF exports lose tables, arrow direction and the link to the source. This server keeps the board's structure and cites every answer to the nodes it came from.

Compared with Figma's MCP server

Figma's official MCP server reads a FigJam board or node with its images (get_figjam) and edits boards (use_figma). This server turns a workshop board into context an assistant can cite and track:

large boards read section by section, with an overview, size-limited pages and search
source IDs in compact overviews, with Figma links in full excerpts and answer citations
tables read row by row
local snapshots, and diff_board to see what changed
explicit credentials redacted before they reach the cache, the output or a model
image descriptions from a vision model you configure

The two work together: in the demo above, Figma's server edits the board and this one reports the change.

Tools

Tool	What it does	LLM call
`ingest_board`	Reads a board, clusters it and saves a local snapshot. Re-ingests reuse unchanged clusters; `focusNodeIds` chooses which sections' images are interpreted first.	In `balanced` (default) and `max_quality` mode
`get_board_context`	Reads saved context, automatically using compact source-ID lines for large section reads; `detail: "full"` returns complete excerpts and Figma links. Also supports topic search and pagination.	No
`answer_from_board`	Answers one specific question (a number, status or decision) from the most relevant excerpts, with node-level citations or an insufficient-evidence result. Not meant for whole-board summaries.	Yes
`diff_board`	Compares snapshots with bounded lists and full totals: clusters, nodes, table cells (0-based), arrows with source IDs, section/frame renames and layout counts. Notes unchanged re-ingests.	No
`diagnose_llm_config`	Tests the configured models with small text and image JSON checks.	Yes

ingest_board also reads Figma design files (/design/, /file/ and /proto/ URLs), but clustering and reading order are made for FigJam boards.

Quick start

Five steps. Requires Node.js 22.12 or later. Step 4 sets the model provider that answer_from_board, diagnose_llm_config and image interpretation need; it is optional.

Node.js. Check the installed version with node --version; install Node.js 22.12 or later if it is older.
Figma token. Create a personal access token under Settings → Security → Personal access tokens with the scope file_content:read. The token's account must be able to open the board. Every ingest_board call is one Figma file download, a Tier 1 request. Figma allows View and Collab seats up to 20 Tier 1 requests a month on every plan, and says the actual limit may be lower (rate limits).
Add the server with the example for your client below. The examples set only FIGMA_ACCESS_TOKEN, so the server starts and ingest_board works in ingestMode: "max_speed" without a model provider. @latest with --prefer-online makes npx check the registry for the latest release on every start, even when package metadata is cached (npm configuration).
Optional: model provider. Add LLM_BASE_URL and LLM_API_KEY to the server's env block, then restart the client. Both are needed together; without them, balanced ingests run text-only and say that the model settings are missing. Example with OpenRouter (create a key):
```
LLM_BASE_URL=https://openrouter.ai/api/v1
LLM_API_KEY=your-openrouter-key
```
In Claude Code, remove the entry with claude mcp remove figjam-context (with the same --scope as when you added it), then add it again with an --env flag for each variable (Claude Code). A local OpenAI-compatible server without sign-in still needs LLM_API_KEY set to any non-empty value. Set LLM_TEXT_MODELS, LLM_FAST_TEXT_MODELS and LLM_VISION_MODELS to its model names (configuration). Then run diagnose_llm_config in step 5.
Check the setup. Ask your assistant to ingest one of your boards with ingestMode: "max_speed", for example "Ingest https://www.figma.com/board/FILE_KEY/Name with ingestMode max_speed." That makes one Figma request and no model call. A working setup answers with a line that starts Ingested board FILE_KEY (snapshot …): and counts the clusters. Clients that show their tools, such as Claude Code with /mcp, list the server there (Claude Code). With a provider from step 4, also run diagnose_llm_config; it checks the configured models with small synthetic inputs. For error messages, see common errors.

All settings: configuration.

Claude Code

claude mcp add --scope user --env FIGMA_ACCESS_TOKEN=your-figma-token --transport stdio figjam-context -- npx -y --prefer-online figjam-context-mcp@latest

--scope user makes the server available in all your projects. Without it, Claude Code stores the server for the current project only (scopes).

For longer ingests, set MCP_TOOL_TIMEOUT=300000 in the environment that launches Claude Code and INGEST_BOARD_VISION_BUDGET_MS=270000 in the server environment, leaving about 30 seconds for the rest of the ingest (Claude Code environment variables).

Claude Desktop

Open Settings → Developer → Edit Config in Claude Desktop. This opens claude_desktop_config.json; the file is at:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the server under mcpServers, keeping any other entries in the file:

{
  "mcpServers": {
    "figjam-context": {
      "command": "npx",
      "args": ["-y", "--prefer-online", "figjam-context-mcp@latest"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "your-figma-token"
      }
    }
  }
}

Then quit Claude Desktop completely and start it again; the server starts with the app (MCP quickstart). The MCP documentation names no tool timeout setting for Claude Desktop, so keep the default image budget.

Codex CLI and ChatGPT desktop app

Add this to ~/.codex/config.toml; the app, CLI and IDE extension share this configuration (OpenAI MCP setup):

[mcp_servers.figjam-context-mcp]
enabled = true
command = "npx"
args = ["-y", "--prefer-online", "figjam-context-mcp@latest"]
startup_timeout_sec = 30
default_tools_approval_mode = "approve"

[mcp_servers.figjam-context-mcp.env]
FIGMA_ACCESS_TOKEN = "your-figma-token"

Without default_tools_approval_mode = "approve", ChatGPT may ask for approval or abort tools with external effects; with it, the client never asks before board content goes to the model provider, so use max_speed and avoid answer_from_board for confidential boards.

For longer ingests, set tool_timeout_sec = 300 under [mcp_servers.figjam-context-mcp] and INGEST_BOARD_VISION_BUDGET_MS = "270000" in its env table, leaving about 30 seconds for the rest of the ingest (OpenAI timeout options).

GitHub Copilot CLI

Add this to ~/.copilot/mcp-config.json (Copilot CLI MCP setup):

{
  "mcpServers": {
    "figjam-context": {
      "type": "local",
      "command": "npx",
      "args": ["-y", "--prefer-online", "figjam-context-mcp@latest"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "your-figma-token"
      },
      "tools": ["*"]
    }
  }
}

For longer ingests, set "timeout": 300000 on the server in ~/.copilot/mcp-config.json and "INGEST_BOARD_VISION_BUDGET_MS": "270000" in its env, leaving about 30 seconds for the rest of the ingest (tested with a 600000 ms timeout).

VS Code

In the Copilot harness, add the server under Global → Copilot Global in Chat: Open Customizations (Command Palette), then MCP Servers. VS Code writes it to ~/.copilot/mcp-config.json, the same file as in the Copilot CLI section, in the portable mcpServers format (VS Code MCP servers, configuration reference):

{
  "mcpServers": {
    "figjam-context": {
      "type": "local",
      "command": "npx",
      "args": ["-y", "--prefer-online", "figjam-context-mcp@latest"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "your-figma-token"
      },
      "tools": ["*"]
    }
  }
}

The portable format has no input variables, so the token is stored in this file. Keep that file in your user directory and out of any repository.

Local harness only: to keep the token out of the file, open MCP: Open User Configuration and use an input marked "password": true. VS Code does not forward servers that need inputs to Copilot harness sessions, so this works only in the Local harness (VS Code MCP configuration):

{
  "inputs": [
    {
      "type": "promptString",
      "id": "figma-token",
      "description": "Figma personal access token (file_content:read)",
      "password": true
    }
  ],
  "servers": {
    "figjam-context": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "--prefer-online", "figjam-context-mcp@latest"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "${input:figma-token}"
      }
    }
  }
}

Do not put tokens in a .vscode/mcp.json in a repository; VS Code's documentation says not to commit tokens or passwords.

In the Local harness, "envFile": "${workspaceFolder}/.env" on the server in mcp.json loads an environment file; the portable format does not support envFile, and the server does not load a working-directory .env itself.

For longer ingests, use the Local harness with a per-server "timeout": 300000 in mcp.json and "INGEST_BOARD_VISION_BUDGET_MS": "270000" in its env (about 30 seconds below the timeout); #343135 reports that remote HTTP tool calls in the Copilot harness, the default in 1.142, ignore that timeout and stop after about 180 seconds, while the Local harness honors it.

Other MCP clients

For clients that accept mcpServers, add this to their MCP configuration:

{
  "mcpServers": {
    "figjam-context": {
      "command": "npx",
      "args": ["-y", "--prefer-online", "figjam-context-mcp@latest"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "your-figma-token"
      }
    }
  }
}

Where the client supports a configurable tool timeout, raise it to about 300 seconds using its documented setting and set INGEST_BOARD_VISION_BUDGET_MS=270000 in the server environment, about 30 seconds below it. Cursor has no configurable timeout: its IDE allows about 60 minutes, while ACP/CLI calls stop at 60 seconds even with progress, so keep the default image budget on that path (Cursor support).

Using the tools

Then ask your assistant to ingest a board URL, for example "Ingest https://www.figma.com/board/FILE_KEY/Name and list the open questions." The boardId of every later call is the file key from that URL, or the URL itself; a URL with a node-id and without nodeIds, topic and outsideSections makes get_board_context read that node. To summarize a board, the assistant calls ingest_board, then get_board_context without parameters, whose first page names the largest sections and includes a section overview with IDs within the page's size limit, and then reads the largest sections by passing their IDs as nodeIds. Several IDs in one call take turns in request order, up to 50 per call. For a whole-board summary, pass all top-level section IDs with maxChars: 24000, follow the cursor in the text with the same arguments, then read outsideSections: true. Large nodeIds reads automatically use short source-ID lines, grouped by section, when the first full page would leave unread excerpts. limit applies only with the full view; an overview ignores it even when supplied. Read complete text and its Figma link with the same boardId and snapshotId, the line's ID in nodeIds, and detail: "full". For a table row, use its table ID. Everything that lies in no section, such as loose notes and tables, comes with outsideSections: true. Compact overviews show the Figma link pattern for their node IDs (URL-encode the ID) and shorten each text to a shared 50–120-character prefix with …; the host writes the summary. Topic searches, outsideSections, single leaf, table or cell IDs and small containers always return the full view.

Inputs are read as hosts and users send them. A node ID in link form (5-87, 5%3A87, I5-87%3B1-2) or a Figma link of the same board with a node-id is read as the ID it stands for (5:87) in nodeIds and focusNodeIds, and the text says so once; an ID that exists in the snapshot is never changed, and a link of another board is an error. A key that differs from a parameter only in case, _ or - (ingest_mode, node_ids) ends the call with "did you mean …" before anything is done; any other unknown key is ignored and named, without its value, in the text and in ignoredArguments of structuredContent. File keys are case-sensitive: an unknown boardId lists the stored boards (at most 10, most recent first) and names a key that differs only in case.

How it works

Pipeline: a FigJam board is read through the Figma API, clustered by geometry, refined with vision and turned into LLM-ready context

Read. ingest_board downloads the board through the Figma REST API on every call. get_board_context and answer_from_board read the saved snapshot without a new request.
Normalize. Nodes become text, table cells, images and connectors, with their pages, sections and named enclosing frames and groups. Tables are read row by row: row and column come from the cell IDs, and each row becomes one excerpt.
Cluster. Nearby nodes are grouped by rotation-aware distance. Arrows between groups become directed relations. Clusters without a model label are named after their section, and an arrow appears in the context once one of its ends, or a section, frame or group around one, is on the page.
Interpret. In balanced mode, clusters with an image, or drawings without any text, get a vision-model summary within a 40-second budget; text clusters, however short, keep their extracted text. A cluster starts only when the time left fits it; unfinished clusters continue on the next ingest. With focusNodeIds, the images of the given sections, frames or nodes come first. In max_quality, one ingest interprets only a few dozen clusters within the 40-second image budget (20–35 on a board with about 300 clusters, measured with 3 parallel requests); the next ingest continues, each costs a Tier 1 file download, and focusNodeIds sets the order.
Serve. The snapshot is saved to a private local cache. Search favors excerpts containing more of the question’s words. get_board_context searches it (BM25 over original text, table rows and names, arrow labels and table headings), answer_from_board answers with citations and diff_board compares snapshots. Topic and question searches match whole words ignoring case and accents (words of five or more letters also match compounds that begin with them), but not other word forms, synonyms or translations. Use the board's words and language; an empty search does not prove the board lacks the topic. Paging, overviews and the detail setting are described in Using the tools. Full-view excerpt text is quoted with > on every line, and model-generated cluster labels are marked as model labels. Text content is the readable page; structuredContent holds each excerpt once, in overview.text (with empty evidence and clusters) or in evidence for the full view. Full excerpts inherit snapshotId from the response; absent chunkIndex means 0 and absent truncated or modelDerived means false, with no inheritance of these flags from a cluster. Named frames and groups appear in frameNames on clusters and on excerpts whose location differs; their names also participate in search.

Models and cost

The default preset student-free uses free OpenRouter models: text and images go to openrouter/free, which picks a free model that supports structured outputs (and images, for images). The free default is best effort: free models change, hit rate limits and time out. A request to openrouter/free or openrouter/auto that fails with a provider error is sent once more, since the router may pick another model. Images go to the model with at most 1,024 px on the longest side; larger ones are scaled down locally.

OpenRouter allows free models 20 requests per minute and 50 requests per day, or 1,000 per day once you have bought at least 10 credits (limits).
Figma limits requests by seat and plan (rate limits). File downloads and image renders are Tier 1: Dev and Full seats on paid plans get 10–20 requests per minute, View and Collab seats and files in Starter plans at most 20 per month. Every ingest_board call is one file download, so a View or Collab seat allows about 20 ingests a month. Images come from the image fills instead, Tier 2 with at least 5 requests per minute, in one request per ingest. Renders are left for drawings without an image and as a fallback for images without a usable original; renders of several clusters share requests of up to 18 nodes, so 30 image clusters without image fills need 2 render requests. max_speed needs neither.
LLM_BASE_URL takes any OpenAI-compatible endpoint; for paid models, set LLM_TEXT_MODELS, LLM_FAST_TEXT_MODELS and LLM_VISION_MODELS, for example all three to openai/gpt-4.1-mini (provider charges apply).
Run diagnose_llm_config after every model change. It checks JSON replies and image understanding with synthetic inputs.

Privacy

The server reads from Figma and never changes a board.
Hidden elements and their descendants are skipped before extraction, image loading and provider requests.
balanced and max_quality ingests send board text and images (originals or renders) to the configured LLM provider. answer_from_board sends the question and selected excerpts. max_speed with get_board_context and diff_board sends nothing to an LLM provider.
Snapshots stay in a private per-user cache on your machine. Delete the cache directory to remove them.
Explicit credentials such as Passwort: … or API keys are redacted before they reach the cache, tool output or an LLM provider (FIGJAM_MCP_REDACT_CREDENTIALS). This is a safety net, not a guarantee: images are not redacted, so keep credentials off the board.
Keep tokens in the client's environment. A token passed as a tool argument can appear in client logs.

Limitations

Image interpretation gets 40 seconds per ingest by default; large boards need several ingests to interpret every image cluster.
A client that cancels an ingest, for example after a 60-second timeout, gets no partial result.
Free models are best effort. Citations show where an answer comes from, not that its conclusion is right.
Search is lexical; synonyms without shared words do not match.
Local stdio only; no hosted or multi-user mode.

Measured results: evaluation.

Development

git clone https://github.com/ecestnrkl/figjam-mcp.git
cd figjam-mcp
npm ci
cp .env.example .env    # optional: add tokens for local development
npm run check           # typecheck, tests, build, package validation
npm run package:smoke   # install the packed package and exercise all tools
npm run eval:retrieval  # offline retrieval and diff evaluation
npx --prefer-online @modelcontextprotocol/inspector --config inspector.config.json

npm run dev and inspector.config.json explicitly load the repository's .env with Node's --env-file-if-exists=.env; existing environment values win. For other launch commands, configure the MCP client's env or set FIGJAM_MCP_ENV_FILE to the absolute path of the file.

See CONTRIBUTING.md and the changelog.