io.github.ecestnrkl/figjam-mcp

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.

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.

Tools

Tool	What it does	LLM call
ingest_board	Reads a board, clusters it and saves a local snapshot. Re-ingests reuse unchanged clusters.	In balanced (default) and max_quality mode
get_board_context	Returns paginated, source-linked context, optionally for a topic or exact node IDs. Use it for overviews, summaries and documentation.	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 two snapshots: new, removed and changed clusters, nodes, table cells and arrows.	No
diagnose_llm_config	Tests the configured models with small text and image JSON checks.	Yes

Quick start

Requires Node.js 22.12 or later.

1. Create a Figma personal access token under Settings → Security → Personal access tokens with the scope file_content:read. Add file_metadata:read so re-ingests of an unchanged board skip the download. The token's account needs access to the board.
2. Optional: create an OpenRouter key at openrouter.ai/keys. It enables image interpretation, answer_from_board and diagnose_llm_config. Without it, use ingestMode: "max_speed" with get_board_context and diff_board.
3. Add the server to your MCP client:

{
  "mcpServers": {
    "figjam-context": {
      "command": "npx",
      "args": ["-y", "figjam-context-mcp"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "your-figma-token",
        "LLM_BASE_URL": "https://openrouter.ai/api/v1",
        "LLM_API_KEY": "your-openrouter-key"
      }
    }
  }
}

For Claude Code:

claude mcp add figjam-context -e FIGMA_ACCESS_TOKEN=your-figma-token -e LLM_BASE_URL=https://openrouter.ai/api/v1 -e LLM_API_KEY=your-openrouter-key -- npx -y figjam-context-mcp

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.

All settings: configuration. Problems: troubleshooting.

How it works

1. Read. ingest_board downloads the board through the Figma REST API. If Figma reports the same version as the last ingest, the download is skipped.
2. Normalize. Nodes become text, table cells, images and connectors, with their pages and sections.
3. Cluster. Nearby nodes are grouped by rotation-aware distance. Arrows between groups become directed relations.
4. Interpret. In balanced mode, clusters with images or little text get a vision-model summary within a 40-second budget; the rest keep their extracted text. Unfinished clusters continue on the next ingest.
5. Serve. The snapshot is saved to a private local cache. get_board_context searches it (BM25 over original text, table cells and names), answer_from_board answers with citations and diff_board compares snapshots.

Models and cost

The default preset student-free uses free OpenRouter models: text goes to nvidia/nemotron-3-super-120b-a12b:free and then openrouter/free; images go to openrouter/free, which picks a free model that accepts images and structured outputs. The free default is best effort: free models change, hit rate limits and time out.

• 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 file downloads and image renders by seat and plan: 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 (rate limits). One render request covers up to 18 screenshots (about three clusters), so a default ingest usually needs at most four; max_speed needs none.
• For a team, configure your own model: LLM_BASE_URL takes any OpenAI-compatible endpoint, and LLM_TEXT_MODELS / LLM_VISION_MODELS set the model lists.
• 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.
• balanced and max_quality ingests send board text and screenshots 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: screenshots 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    # add your tokens
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 @modelcontextprotocol/inspector --config inspector.config.json

See CONTRIBUTING.md and the changelog.

License

MIT © 2026 ecestnrkl