figma-comments-mcp

An MCP server that lets Claude read your Figma comments and Dev Mode annotations. Read-only. Scoped to the frame you link.

Design feedback lives in Figma. The agent can't see it. So every round of changes meant reading comments in Figma, retyping them into Claude, and pasting the result back — with me as the copy-paste layer in the middle.

Now: leave the comments where you already leave them, paste the frame link, and ask.

"Read the comments on figma.com/design/abc123/…?node-id=132-5 and apply them."

I wrote about why I built it here: figma-comments-mcp: an MCP server so Claude can read your comments.

---

What Claude sees

A comment arrives resolved to the layer it's pinned to — the layer name, not a node id — so the agent knows what the feedback is about:

rNK3UkoeLnbBHHYQiv9MW8 · frame 132:5 "01 · Results — default" · 1 thread · 1 annotation

1873426532 · Eun Ji Jung · 2026-08-05 19:22
  on 132:5 "01 · Results — default" FRAME
  have hover states

annotation on 132:258 "Overview" FRAME
  allow for collapsing panels

The two tools

list_figma_comments — comment threads and Dev Mode annotations on a file, or on one frame within it, each resolved to its layer.

get_figma_comment_image — renders the layer a comment is pinned to. For when the note is spatial ("too much space here") and the words alone don't carry it, or when it's pinned to a pasted screenshot whose layer name is something useless like image 21.

It only reads

It never writes to Figma, edits your designs, or posts replies. The token it asks for is read-only on both scopes, and there is no code path that mutates anything.

Two behaviours worth knowing

A frame link reads only that frame. Any Figma URL copied with a frame selected carries ?node-id=, and the tool scopes to it — including everything nested inside, excluding the section around it. It always reports how many threads it left out. Pass scope: "file" for the whole file.

Annotations are not comments. Dev Mode annotations are a separate Figma feature, invisible to the comments API, and easy to forget you left. Both counts are on the headline so a frame never looks emptier than it is.

---

Setup

Node 20 or newer. Five steps, and step 4 is the one everyone misses.

1. Clone and build

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

The client runs dist/, not src/, so the build isn't optional.

2. Make a Figma token

Figma → your avatar → Settings → Security → Personal access tokens → Generate new token.

You need two scopes, both read-only:

Scope	Set to
File content	Read-only
Comments	Read-only

File content alone is the easy mistake — the server starts fine, resolves layer names fine, then returns a 403 the moment it asks for comments.

Copy the token when it's shown. Figma won't show it again.

3. Point your client at it

Claude Code:

claude mcp add figma-comments --env FIGMA_TOKEN=figd_your_token_here -- node /absolute/path/to/figma-comments-mcp/dist/index.js

Claude Desktop — edit ~/Library/Application Support/Claude/claude_desktop_config.json (Windows: %APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "figma-comments": {
      "command": "node",
      "args": ["/absolute/path/to/figma-comments-mcp/dist/index.js"],
      "env": { "FIGMA_TOKEN": "figd_your_token_here" }
    }
  }
}

The path must be absolute — ~ won't resolve.

4. Restart the client

MCP servers are spawned once at launch. Editing the config or rebuilding dist/ does nothing to a session that's already running. This catches everyone at least once.

5. Check it works

Before involving the client at all:

FIGMA_TOKEN=figd_your_token_here npm run try -- "https://figma.com/design/<key>/...?node-id=1-2"

If that prints threads and your client shows nothing, the problem is the config or the restart — not the token.

---

Using it

Copy a link from Figma with the frame selected, and ask:

"Read the comments on https://figma.com/design/abc123/...?node-id=132-5 and apply them."

"What's still open across the whole file?"

"What did I annotate on this frame?"

The first is the one that changes your day. The feedback goes straight from where the reviewer left it into the change, without passing through you.

---

Troubleshooting

What you see	What it is
403 on every call	Token is missing the Comments scope, or it expired. File content alone isn't enough.
403 on some calls only	Token works, but the account can't see this file. Check you can open it in the browser as the same user.
404 on a file that exists	Wrong file key, or the file belongs to an org the token's account isn't in.
429	Figma rate limit. Wait and retry.
FIGMA_TOKEN is not set	The client isn't passing the env var — it goes in the server's env block, not your shell.
Server not listed in the client	Restart it. See step 4.
Changes to src/ do nothing	npm run build, then restart the client.
No node "1:2" in this file	The node-id is from a different file. Pass scope: "file" to search everything.

---

How it's built

• TypeScript on @modelcontextprotocol/server v2, over stdio. Hits the Figma REST API with fetch — no SDK.
• Auth is the X-Figma-Token header. figd_ tokens reject Authorization: Bearer, which is the first thing to check on a 401 or 403.
• Read-only endpoints used: /v1/files/:key/comments, /v1/files/:key/nodes, /v1/files/:key, /v1/images/:key.
• Built with Claude.

Related

• ds-specs — a Claude Skill that builds design systems an LLM can follow, with a two-way Figma bridge.
• More of what I'm figuring out about designing with agents.

License

ISC. See LICENSE.