figma-comments-mcp

![CI](https://github.com/junsimon/figma-comments-mcp/actions/workflows/ci.yml) ![License: MIT](./LICENSE) ![Node](https://nodejs.org) ![Model Context Protocol](https://modelcontextprotocol.io)

A local MCP server that lets Claude (or any MCP client) read, understand, and act on comments in Figma _and_ FigJam — the layer the official Figma Dev Mode MCP doesn't expose.

Works on both Figma design files (figma.com/design/…) and FigJam boards (figma.com/board/…), so it fits the whole arc of a project: design reviews, design QA, and the messy collaborative middle — workshops, brainstorms, retros, and jams where the thinking lives in pinned comments on stickies and frames.

Why this exists: clients, reviewers, and workshop participants leave most of their feedback as comments pinned onto the canvas. AI assistants can read the design itself — layers, screenshots, code — but not those pinned comments, so the feedback never actually makes it into the work. This server closes that gap: Claude reads the comments and knows exactly which layer or sticky each one points to, so _"make this blue"_ becomes _"make Checkout / CTA Button blue."_

The official Figma MCP gives an AI assistant the design tree, screenshots, variables, and code, but not comments. Clients, reviewers, and workshop participants leave most of their feedback as comments pinned onto the canvas. This server wraps the Figma REST comments API and, crucially, resolves which node each comment is pinned to — a layer in a design file, or a sticky/shape/section in a FigJam board (name + breadcrumb path + node id) — so feedback like _"make this blue"_ becomes actionable: _"comment on Checkout / CTA Button (node 1:360): make this blue."_

It composes alongside the official Figma MCP — that one reads design structure and writes design changes; this one adds the missing comment layer.

┌─────────┐   reads comments     ┌──────────────────────┐
│ Claude  │ ───────────────────▶ │  figma-comments-mcp  │ ──▶ Figma REST API
│ (MCP    │                      │      (this repo)     │     /v1/files/:key/comments
│ client) │ ◀─────────────────── └──────────────────────┘
│         │   reads/writes design ┌──────────────────────┐
│         │ ◀──────────────────▶  │  Figma Dev Mode MCP  │ ──▶ Figma (official)
└─────────┘                       └──────────────────────┘

Tools
Sample output
How comment → node mapping works
Quick start
Register with an MCP client
CLI
Configuration
Development
Contributing · Security · License

Tools

Read (always available):

| Tool | What it does | |---|---| | get_comments_summary | Counts (total/open/resolved), open threads grouped by target page/frame, one-line digest per open thread. Start here. | | list_comments | All threads, grouped, each enriched with its target node. Open-only by default. | | get_comment_thread | One full thread (root + replies + reactions + resolved state + target node). | | render_comment_target | Renders the node a comment is pinned to (or an explicit node_id) and returns the image so the assistant can see it. |

Write (only when FIGMA_ENABLE_WRITES=true, and each defaults to a dry_run preview):

| Tool | What it does | |---|---| | reply_to_comment | Post a reply to a thread (e.g. "Done — changed the button to blue"). | | react_to_comment | Add an emoji reaction (default :white_check_mark:) as a lightweight "addressed" marker. | | post_comment | Place a new pinned comment at a node or coordinate. |

Resolution limitation: the Figma REST API has no endpoint to resolve a comment — resolved_at can only be set in the Figma UI. Use a reply or a :white_check_mark: reaction as the machine-writable "addressed" signal.

Sample output

get_comments_summary returns an at-a-glance overview — counts, open threads grouped by where they sit, and a one-line digest of each:

Comments: 12 total, 4 open, 8 resolved.

Open threads by target:
  - Checkout / Payment: 2
  - Home / Hero: 1
  - (unpinned): 1

Open threads:
  #3 Checkout / CTA Button: make this blue
  #7 Checkout / Card field: the label is cut off on mobile
  #9 Home / Hero: can we try a lighter headline?
  #11 (unpinned): overall looks great, ship it

list_comments / get_comment_thread return the full thread, each tied to the exact layer it's pinned to:

#3  [OPEN]  @jane  2026-06-10
Target: Checkout / CTA Button  (node 1:360)
"make this blue"
  └ reply @simon: "on it"
  ✅ x1

The (node 1:360) is the part the official Figma MCP can't give you: it tells the assistant precisely which layer the feedback is about.

How comment → node mapping works

Each comment carries client_meta in one of four shapes:

FrameOffset / FrameOffsetRegion — has a node_id → direct lookup of the node name, type, and breadcrumb path (a layer in Figma, a sticky/shape/section in FigJam).
Vector / Region — bare absolute coordinates → the server fetches the file's node tree and returns the deepest node whose bounding box contains the point, flagged [inferred] so you know the mapping is heuristic.

The file tree is fetched once and cached in-memory (TTL, default 60s) so enrichment doesn't refetch for every comment.

Quick start

Requirements: Node 20+ and npm.

1. Create a Figma Personal Access Token

Figma → Settings → Security → Personal access tokens. Select these scopes when creating it:

file_comments:read — read comments & reactions (required)
file_content:read — read the node tree for enrichment + render images (required)
file_comments:write — post replies/reactions/comments (only if you enable writes)

2. Install and build

git clone https://github.com/junsimon/figma-comments-mcp.git
cd figma-comments-mcp
npm install
npm run build

3. Provide the token

Copy .env.example to .env and set FIGMA_TOKEN:

cp .env.example .env
# edit .env and paste your token

The server and CLI auto-load .env from the project root. (Alternatively, pass FIGMA_TOKEN via the MCP client's env block — see below.) .env is gitignored.

4. Verify with the CLI

node dist/cli.js "https://www.figma.com/design/<KEY>/<name>" --summary   # Figma design file
node dist/cli.js "https://www.figma.com/board/<KEY>/<name>" --summary     # FigJam board

You should see comment counts and a one-line digest per open thread. A bare file key works too, and /design/, /board/, /file/, and /proto/ URLs are all accepted.

Register with an MCP client

The server speaks MCP over stdio. For Claude Code, either run:

claude mcp add figma-comments \
  -e FIGMA_ENABLE_WRITES=false \
  -- node /absolute/path/to/figma-comments-mcp/dist/index.js

…or add it to your MCP config (.mcp.json / claude_desktop_config.json / etc.):

{
  "mcpServers": {
    "figma-comments": {
      "command": "node",
      "args": ["/absolute/path/to/figma-comments-mcp/dist/index.js"],
      "env": {
        "FIGMA_TOKEN": "<your token>",
        "FIGMA_ENABLE_WRITES": "false"
      }
    }
  }
}

Replace /absolute/path/to/figma-comments-mcp with the real path on your machine — that string is a placeholder, not a literal value. If you copy it verbatim, the client will fail to start the server with Error: Cannot find module '/absolute/path/to/figma-comments-mcp/dist/index.js'. Run pwd in the cloned repo to get the path, and make sure you've built it (npm run build) so dist/index.js exists. The same applies to the claude mcp add command above.

If you keep the token in .env, you can omit FIGMA_TOKEN from the config above. Set FIGMA_ENABLE_WRITES to true to expose the write tools — even then, every write defaults to a dry_run preview, so the assistant must pass dry_run:false to actually mutate a shared file. Restart the client after registering.

CLI (for debugging)

node dist/cli.js "<figma file url>"                    # enriched comment blocks (open only)
node dist/cli.js "<figma file url>" --include-resolved  # include resolved
node dist/cli.js "<figma file url>" --summary           # counts + digest
node dist/cli.js "<figma file url>" --json              # raw enriched JSON

During development you can skip the build with npm run cli -- "<url>" (via tsx).

Configuration reference

| Env var | Default | Purpose | |---|---|---| | FIGMA_TOKEN | — (required) | Personal Access Token. | | FIGMA_ENABLE_WRITES | false | Register the write tools. | | FIGMA_TREE_TTL_MS | 60000 | In-memory file-tree cache TTL. | | FIGMA_TREE_DEPTH | 4 | Max node-tree depth fetched for pin enrichment. Bounds the payload so large files don't drop the connection. 0 = unbounded. |

All can be set in the environment or in .env.

Development

npm test          # vitest — URL parsing, enrichment hit-test, threading
npm run typecheck # tsc --noEmit
npm run dev       # run the server from source via tsx
npm run cli -- "<url>"   # run the CLI from source

CI (GitHub Actions) runs typecheck, build, and tests on Node 20.

Contributing

Contributions are welcome — see CONTRIBUTING.md. Please don't commit secrets or paste tokens into issues/PRs.

Security

Keep your token in .env (gitignored), grant it the minimum scopes you need, and revoke any token that leaks. The server only ever sends the token to Figma's API. Found a vulnerability? Email simonjun@simonjun.cz rather than opening a public issue.

figma-comments-mcp