Claude AI Agents Talk to Figma MCP

Enable your AI agents to read, analyze, and modify Figma designs.

🌐 Language / ভাষা: English guide · বাংলা নির্দেশিকা

Works with your favorite agentic tools:

• Claude Desktop

• Claude Code

• Cursor

• Antigravity

• Windsurf

• VS Code + GitHub Copilot

• Cline

• Roo Code

👩🏽‍💻 Who it's for

UX/UI Teams

Automate repetitive design tasks and maintain brand consistency without manual effort:

• Automated accessibility audits - Detect and fix contrast issues in seconds

• Bulk style updates - Change colors, typography, or spacing across the entire document with a single command

• Visual hierarchy analysis - Get instant feedback on your design structure

• Comment triage - Read every review thread you're involved in and reply in bulk, without leaving the chat

Developers

Generate production-ready code directly from designs:

• React/Vue/SwiftUI components - From design to code in one step

• Code with design tokens - Keep design and development in sync

• Reduce handoff friction - Fewer back-and-forth iterations with the design team

Key advantage: Unlike Figma's official MCP which requires a Dev Mode license, this MCP works with any Figma account (even free ones).

Comments included: Figma's Plugin API cannot see comments at all — they only exist in the REST API. This MCP bridges both, so your agent can read and reply to review threads as well as edit the canvas. See Comment tools.

Related MCP server: MCP Figma

💡 Real-world use cases

Accessibility:

"Find all text with contrast ratio <4.5:1 and suggest colors that meet WCAG AA"

Rebranding:

"Change #FF6B6B to #E63946 in all primary buttons throughout the document"

Design analysis:

"Analyze the visual hierarchy of this screen and suggest improvements based on design principles"

Developer handoff:

"Generate the React component for 'CardProduct' including PropTypes and styles in CSS modules"

Review triage:

"Show me every unresolved comment I'm involved in across the team, flag the ones waiting on my reply, and draft an answer for each"

🚀 Installation — complete beginner's guide

Time needed: ~15 minutes the first time. About 20 seconds every day after that.

This guide assumes zero prior experience. Every command is written out in full. If you have never opened a terminal before, that's fine — start at Step 0.

💡 Written for macOS. Windows differences are called out in 🪟 Windows notes under each step.

🧠 First, understand what you're installing

This is not a single app. It's three pieces that talk to each other. Knowing this makes every later step (and every error message) make sense.

┌─────────────────┐        ┌──────────────────┐        ┌─────────────────┐
│  Claude Desktop │◄──────►│  WebSocket server│◄──────►│  Figma Desktop  │
│                 │  MCP   │  (localhost:3055)│   WS   │  + this plugin  │
│  1. Extension   │        │  2. Terminal     │        │  3. Plugin      │
└─────────────────┘        └──────────────────┘        └─────────────────┘

All three must be running at the same time. If any one is missing, Claude will say it can't reach Figma. That's the single most common problem people hit — see Troubleshooting.

Step 0: Open the Terminal

You'll need it for a few copy-paste commands. You do not need to understand them.

1. Press Cmd + Space

2. Type Terminal

3. Press Enter

A window with white or black text appears. That's the terminal. To run a command: copy it, paste it (Cmd + V), press Enter, and wait until the text stops scrolling and you get a fresh prompt line back.

🪟 Windows: press Win, type PowerShell, press Enter.

Step 1: Install the four prerequisites

1a. Node.js

Check whether you already have it — paste this and press Enter:

node -v

• ✅ You see something like v22.14.0 (any number 18 or higher) → skip to 1b.

• ❌ You see command not found → go to nodejs.org, click the green "Download Node.js (LTS)" button, open the downloaded .pkg file, and click Continue through every screen of the installer.

Then quit and reopen Terminal and run node -v again to confirm.

1b. Bun (required, do not skip)

The bridge server (piece #2) is built on Bun and will not run on Node alone. Skipping this is the #1 reason the setup fails.

Check:

bun -v

If you get command not found, install it:

curl -fsSL https://bun.sh/install | bash

When it finishes, quit and reopen Terminal, then verify:

bun -v

You should see a version number like 1.2.4.

🪟 Windows: run powershell -c "irm bun.sh/install.ps1 | iex" instead.

1c. Figma Desktop app

Download from figma.com/downloads.

⚠️ The browser version of Figma will not work. Local plugin development requires the desktop app. Install it even if you normally use Figma in Chrome.

1d. Claude Desktop

Download from claude.ai/download. Sign in.

⚠️ Same rule: the desktop app, not claude.ai in a browser. Browser Claude cannot load extensions.

✅ Checkpoint — before continuing, node -v and bun -v should both print version numbers, and both Figma Desktop and Claude Desktop should open.

Step 2: Download this project and build it

Copy this whole block at once, paste it into Terminal, press Enter:

cd ~/Documents
git clone https://github.com/litoondev/claude-talk-to-figma-mcp-main.git
cd claude-talk-to-figma-mcp-main
npm install
npm run build

Plain English, line by line:

💡 There is one more important command: npm run socket. It starts the bridge server that connects Claude to Figma. You'll run it in Step 6a every time you use the tool — not during install.

This folder is now your home base. You'll come back to it every time you use the tool. Remember where it is: Documents/claude-talk-to-figma-mcp-main.

Install Apple's developer tools, then re-run the block above:

xcode-select --install

A dialog appears — click Install and wait for it to finish.

Alternatively, skip git entirely: download the project as a ZIP from the GitHub page (green Code button → Download ZIP), unzip it into Documents, then run npm install and npm run build inside the unzipped folder.

Warnings (WARN, deprecated) are cosmetic — ignore them. Only stop if you see the word ERR! and the command exits without finishing.

🪟 Windows: use npm run build:win instead of npm run build, and cd $HOME\Documents instead of cd ~/Documents.

Step 3: Build the Claude Desktop extension

The GitHub Releases page only carries an old build, so build the current one yourself. Still inside the project folder, run:

npx dxt pack . claude-talk-to-figma-mcp.mcpb

When it finishes (about 30 seconds), the project folder contains claude-talk-to-figma-mcp.mcpb, the file you install in the next step.

💡 npx dxt is the packaging tool that npm install already downloaded. Nothing else to install.

🪟 Windows: the command is the same.

Older instructions (npm run build:dxt, npm run pack) create extra copies named .dxt. They contain exactly the same thing, since Anthropic renamed the format from DXT to MCPB. Use the .mcpb and delete the .dxt copies if you like. Only use a .dxt if a very old Claude Desktop refuses the .mcpb.

Step 4: Install the extension into Claude Desktop

1. Open Finder — click the blue-and-white smiley-face icon in your Dock, or press Cmd + Space, type Finder, press Enter

2. In the sidebar on the left, click Documents, then open the claude-talk-to-figma-mcp-main folder

3. Double-click claude-talk-to-figma-mcp.mcpb

4. Claude Desktop opens and shows an install prompt → click Install

5. It will ask for a Figma personal access token → leave the field blank and click Continue. This is optional and only needed for comment tools — you can add it later in Step 7.

6. Quit Claude Desktop completely — press Cmd + Q (do not just click the red × to close the window) — then reopen it

Alternative if double-clicking does nothing: Open Claude Desktop → Settings (gear icon or top menu) → Extensions tab → drag the .mcpb file and drop it anywhere onto that Extensions page.

✅ Checkpoint — go to Claude Desktop → Settings → Extensions. You should see Claude Talk to Figma listed and enabled.

Right-click the file → Open With → Claude. If Claude isn't listed, choose Other…, navigate to Applications, and pick Claude.

Try the other file — double-click the .dxt instead of the .mcpb. If both fail, update Claude Desktop to the latest version and retry.

Step 5: Install the plugin inside Figma

1. Open the Figma Desktop app

2. Open any design file (or create a new one)

3. Click the Figma logo (the "F" icon) in the very top-left corner of the app → Plugins → Development → Import plugin from manifest…

4. In the file picker, navigate to:

   Documents → claude-talk-to-figma-mcp-main → src → claude_mcp_plugin → manifest.json

5. Select manifest.json and click Open

💡 Can't see the src folder in the picker? Press Cmd + Shift + G and paste ~/Documents/claude-talk-to-figma-mcp-main/src/claude_mcp_plugin to jump straight there.

✅ Checkpoint — Plugins → Development now lists Claude Talk to Figma. You only do this once, ever.

Step 6: Run it — the daily routine

These are the only steps you repeat in future sessions.

6a. Start the bridge server

Open Terminal and run:

cd ~/Documents/claude-talk-to-figma-mcp-main
npm run socket

You should see:

Claude to Figma WebSocket server running on port 3055
Status endpoint available at http://localhost:3055/status

🚨 Leave this Terminal window open. Closing it, or pressing Ctrl + C, kills the bridge and Claude immediately loses Figma. Just push the window aside.

Want to double-check it's alive? Open http://localhost:3055/status in a browser.

Bun isn't installed. Go back to Step 1b. This server genuinely cannot run on Node.

The server is already running in another Terminal window — you're done, just use that one. To force-stop it: pkill -f socket.js

6b. Open the plugin in Figma

In your Figma file: Plugins → Development → Claude Talk to Figma.

A small panel opens showing a channel ID in bold inside a green box — something like a4f9c2.

⚠️ This ID changes every time you reopen the plugin. Never reuse an old one — always copy a fresh one.

→ Copy that 6-character ID now. You'll paste it into Claude in the very next step.

💡 See a Connect button instead of an ID? Click it. The ID appears once the plugin reaches the bridge server. If it never does, the server from Step 6a isn't running.

💡 Shortcut: click the ID itself. It copies the whole message Connect to Figma, channel … so you can paste it straight into Claude.

6c. Connect Claude

In Claude Desktop, type the message below — but replace a4f9c2 with the ID you just copied from the plugin panel:

Connect to Figma, channel a4f9c2

🔑 a4f9c2 is just an example. Your real ID will look similar but be different — something like d7b3f1 or c90ae4. You must use your own ID or Claude won't connect.

Claude confirms the connection. Now test it:

What's currently selected in Figma?

Select any layer in Figma first, then ask. If Claude describes it — you're fully set up. 🎉

Step 7: Optional comment tools

Skip unless you want Claude to read and reply to Figma comments. Everything else already works without this.

Figma's Plugin API cannot see comments at all, so those specific tools go through Figma's REST API, which needs a token.

1. In Figma: your avatar → Settings → Security tab → Personal access tokens → Generate new token

2. Enable these scopes:

   • files:read — read files and comments

   • file_comments:write — post replies

3. Copy the token immediately (Figma shows it only once). It starts with figd_.

4. In Claude Desktop: Settings → Extensions → Claude Talk to Figma → paste the token into the Figma personal access token field

5. Quit Claude (Cmd + Q) and reopen

6. Verify by asking: Check my Figma account

🔒 This token can read every file your account can open. Never commit it to a repo or paste it into a chat.

📅 Every session after the first

Setup is permanent. Daily use is three things, ~20 seconds:

cd ~/Documents/claude-talk-to-figma-mcp-main && npm run socket

1. ✅ Run the command above (leave the Terminal window open)

2. ✅ Figma → Plugins → Development → Claude Talk to Figma → copy the channel ID from the green box

3. ✅ Tell Claude: Connect to Figma, channel and then paste your ID — e.g. Connect to Figma, channel d7b3f1

🧹 Optimize layers & convert to Grid

Clean up messy layer trees (empty frames, useless groups, Frame > Frame > Card double nesting) and turn card rows into a real Figma Grid, without changing how the design looks.

How to use it

1. In Figma, select one section or frame, for example # Work Process. Don't select a whole page of 100+ sections.

2. Tell Claude:

   Optimize the layers of the selected section

3. Claude first scans (nothing changes yet), then asks you about anything that needs a decision:

   Claude asks	What it means	Your answer
   "N hidden layers were found. Do you want to remove them?"	Hidden layers may be alternate states you kept on purpose	Yes to delete them, No to keep them
   ""Card" has a prototype interaction — remove it?"	Removing it could break your prototype, an effect, an export or a mask	Decide for each one
   ""# Work Process" can become a 4-column Grid… Convert it?"	The heading and cards can sit directly inside a Grid, with the wrapper frames removed	Yes to convert

4. Claude applies only what you approved and reports what changed.

What it does automatically (no question needed)

• Removes empty and zero-size layers

• Collapses wrapper frames that do nothing: a single child exactly the same size, no padding, no fill, no stroke, no clip

• Hands the wrapper's Fill sizing to the child, so the layout stays identical

What it never does

• Never deletes a hidden layer, or a layer with a prototype interaction, effect, export setting or mask, without your "yes"

• Never deletes main components, component-property layers or variant layers

• Never changes text, fonts, colours, spacing values or variables

• Never enters component instances

How the Grid conversion stays safe

• The column count is read from your design: 4 equal cards means 4 equal columns (repeat(4, 1fr)).

• Gaps and padding keep their variables (row gap = the section's gap, column gap = the row's gap).

• After converting, the plugin measures every heading and card. If anything moved by more than 1px, or Figma refuses a step, it undoes the conversion and tells you why. Each conversion is one Cmd + Z.

• A section is only proposed when a Grid can reproduce it exactly: one heading, one row of equal-width items, no padding or background on the row.

⚠️ If a Grid conversion is not applied, don't "fix" it by ungrouping. Ungrouping an Auto Layout row stacks the cards, and moving them back by hand leaves a frame with fixed positions and no layout. It looks right but no longer adapts. Report the reason instead.

🌐 Convert an HTML file or website to Figma

Turn a web page into a Figma design that looks exactly like the page: every section, text, image and icon. It's linked to your file's own styles and variables, with a clean, flat layer tree.

How to use it

1. In Figma, open the file whose design system (colour variables, text styles, spacing tokens) you want the import to use.

2. Take a full-page screenshot of the website or HTML page and send it to Claude. It's the reference Claude compares the result against at the end.

3. Tell Claude one of these:

   Convert https://example.com to Figma

   Convert /Users/YOUR_NAME/Desktop/page.html to Figma

   💡 A local file needs its full path, and must be on the same computer as Claude Desktop. To get the path on a Mac: select the file in Finder, hold Option, right-click → Copy "page.html" as Pathname.

4. Claude works through these steps and tells you what it is doing:

   Step	What happens
   1. Analyse	Reads the page and its CSS: sections, text, colours, fonts, spacing, radii, every image and icon, and whether each block is a grid or a row/column
   2. Match	Compares every value with your design system: use from the system / close but not exact / not in the system
   3. Build	Binds your variables and text styles where they match exactly; builds everything else with the page's own values. Places every image and icon. Uses Grid or Auto Layout per container (table below)
   4. Components	An element that appears 2 or more times with no exact component in your file becomes a new component in a frame named Components — from HTML beside the page, and the page uses instances of it. Elements that appear once stay plain layers
   5. Import Notes	A frame beside the design listing what was not in your design system, the new components, and anything that could not be made identical
   6. Compare	Exports the result and compares it with your screenshot, fixing differences until nothing differs; then runs the layer scan, asking before removing anything

The rules it follows

• Identical. Nothing is left out, nothing is added, nothing is restyled or simplified. If something truly can't be reproduced, Claude says so in Import Notes instead of approximating it.

• Linked to your style guide. A colour, text style, spacing or radius that exists in your design system is bound to it, never typed. A "close" style or component is not used, because it would change the design.

• No new variables or styles. The only things created are components for repeated elements.

Grid or Auto Layout?

Good to know

• Images are downloaded by the plugin's server (place_html_image) and placed at their exact size, from websites or from files next to a local .html page. Icons (inline SVG) are placed as vectors, including icons that come from an icon sprite. An image that can't be fetched keeps its exact-size frame, named Image-Missing-…, so the layout doesn't shift.

• It reads the page's HTML and CSS, not a live browser. Pages that build their content with JavaScript after loading may come in incomplete. For those, open the page in Chrome → File → Save Page As… → Webpage, Complete, and convert the saved .html file.

• Pages behind a login can't be read. Save them as above.

• Fonts must be installed on your computer for Figma to use them.

🔄 Update to the newest version

When this repository gets new features, update like this (about 3 minutes):

cd ~/Documents/claude-talk-to-figma-mcp-main
git pull
npm install
npm run build
npx dxt pack . claude-talk-to-figma-mcp.mcpb

Then:

1. Double-click the new claude-talk-to-figma-mcp.mcpb → Install / Replace

2. Quit Claude Desktop completely (Cmd + Q) and reopen it

3. In the Terminal running the bridge, press Ctrl + C, then start it again with npm run socket

4. In Figma, close the plugin and open it again (it loads the new plugin code), and connect with the new channel ID

🔑 Skipping step 1 or 2 is the #1 reason "nothing changed". Claude Desktop keeps running the extension you installed before until you reinstall it and restart. The version number in Settings → Extensions may not change, so don't rely on it.

🪟 Windows: use npm run build:win instead of npm run build, and cd $HOME\Documents\claude-talk-to-figma-mcp-main.

🇧🇩 বাংলা নির্দেশিকা — একদম নতুনদের জন্য

সময় লাগবে: প্রথমবার প্রায় ১৫ মিনিট। এরপর প্রতিদিন মাত্র ২০ সেকেন্ড।

এই নির্দেশিকা ধরে নিচ্ছে আপনি আগে কখনো Terminal ব্যবহার করেননি। প্রতিটি কমান্ড পুরোটা লেখা আছে, শুধু কপি করে পেস্ট করবেন। কমান্ডগুলো ইংরেজিতেই থাকবে, এগুলো বদলাবেন না।

💡 নির্দেশিকাটি macOS-এর জন্য লেখা। Windows-এ যেখানে আলাদা, সেখানে 🪟 Windows লেখা আছে।

🧠 আগে বুঝে নিন কী ইনস্টল করছেন

এটা একটা অ্যাপ নয়, তিনটি অংশ একসাথে কাজ করে:

┌─────────────────┐        ┌──────────────────┐        ┌─────────────────┐
│  Claude Desktop │◄──────►│  ব্রিজ সার্ভার      │◄──────►│  Figma Desktop  │
│  ১. এক্সটেনশন     │        │  ২. Terminal-এ চলে │        │  ৩. প্লাগইন        │
└─────────────────┘        └──────────────────┘        └─────────────────┘

তিনটিই একসাথে চালু থাকতে হবে। যেকোনো একটা বন্ধ থাকলে Claude বলবে সে Figma-তে পৌঁছাতে পারছে না। এটাই সবচেয়ে সাধারণ সমস্যা।

ধাপ ০: Terminal খুলুন

1. কিবোর্ডে Cmd + Space চাপুন

2. Terminal লিখুন

3. Enter চাপুন

একটা লেখাভরা উইন্ডো খুলবে, এটাই Terminal। কমান্ড চালাতে: কমান্ড কপি করুন → Terminal-এ পেস্ট করুন (Cmd + V) → Enter চাপুন → লেখা থামা পর্যন্ত অপেক্ষা করুন।

🪟 Windows: Win কী চাপুন, PowerShell লিখে Enter চাপুন।

ধাপ ১: চারটি প্রয়োজনীয় জিনিস ইনস্টল করুন

১ক. Node.js

আগে থেকে আছে কিনা দেখুন:

node -v

• ✅ v22.14.0-এর মতো কিছু দেখালে (18 বা তার বেশি) → ১খ-তে যান।

• ❌ command not found দেখালে → nodejs.org-এ গিয়ে সবুজ "Download Node.js (LTS)" বাটনে ক্লিক করুন, ডাউনলোড হওয়া ফাইল খুলে Continue চাপতে থাকুন।

তারপর Terminal বন্ধ করে আবার খুলুন, আর node -v আবার চালিয়ে দেখুন।

১খ. Bun (অবশ্যই লাগবে, বাদ দেবেন না)

ব্রিজ সার্ভার Bun ছাড়া চলবেই না। এই ধাপ বাদ দেওয়াই সেটআপ ব্যর্থ হওয়ার ১ নম্বর কারণ।

bun -v

command not found দেখালে ইনস্টল করুন:

curl -fsSL https://bun.sh/install | bash

শেষ হলে Terminal বন্ধ করে আবার খুলুন, তারপর bun -v চালান। 1.2.4-এর মতো ভার্সন দেখাবে।

🪟 Windows: এর বদলে চালান powershell -c "irm bun.sh/install.ps1 | iex"

১গ. Figma Desktop অ্যাপ

figma.com/downloads থেকে ডাউনলোড করুন।

⚠️ ব্রাউজারের Figma-তে কাজ করবে না। ডেস্কটপ অ্যাপ লাগবেই।

১ঘ. Claude Desktop

claude.ai/download থেকে ডাউনলোড করে সাইন ইন করুন।

⚠️ ব্রাউজারের claude.ai নয়, ডেস্কটপ অ্যাপ লাগবে। ব্রাউজারে এক্সটেনশন চলে না।

✅ যাচাই: node -v আর bun -v দুটোই ভার্সন দেখাচ্ছে, আর Figma Desktop ও Claude Desktop দুটোই খুলছে।

ধাপ ২: প্রজেক্ট ডাউনলোড করে বিল্ড করুন

নিচের পুরো ব্লকটা একসাথে কপি করে Terminal-এ পেস্ট করুন, তারপর Enter:

cd ~/Documents
git clone https://github.com/litoondev/claude-talk-to-figma-mcp-main.git
cd claude-talk-to-figma-mcp-main
npm install
npm run build

এই ফোল্ডারটাই আপনার মূল জায়গা: Documents/claude-talk-to-figma-mcp-main। প্রতিবার এখানেই ফিরে আসবেন।

❓ git: command not found দেখালে: xcode-select --install চালান, যে উইন্ডো আসবে সেখানে Install চাপুন, তারপর উপরের ব্লকটা আবার চালান। অথবা GitHub পেজ থেকে সবুজ Code বাটন → Download ZIP → Documents-এ unzip করুন → সেই ফোল্ডারে npm install আর npm run build চালান।

❓ লাল রঙের WARN বা deprecated লেখা এলে: চিন্তার কিছু নেই, উপেক্ষা করুন। শুধু ERR! লেখা এসে কমান্ড মাঝপথে থেমে গেলে সমস্যা।

🪟 Windows: npm run build-এর বদলে npm run build:win, আর cd ~/Documents-এর বদলে cd $HOME\Documents লিখুন।

ধাপ ৩: Claude Desktop-এর এক্সটেনশন ফাইল তৈরি করুন

একই ফোল্ডারে থেকে এটা চালান:

npx dxt pack . claude-talk-to-figma-mcp.mcpb

প্রায় ৩০ সেকেন্ড পর ফোল্ডারে claude-talk-to-figma-mcp.mcpb ফাইল তৈরি হবে। পরের ধাপে এটাই ইনস্টল করবেন।

💡 ফোল্ডারে .dxt ফাইলও দেখলে ঘাবড়াবেন না। ওগুলো একই জিনিসের পুরোনো নামের কপি। সবসময় .mcpb ব্যবহার করুন।

ধাপ ৪: Claude Desktop-এ এক্সটেনশন ইনস্টল করুন

1. Finder খুলুন → বাঁ পাশে Documents → claude-talk-to-figma-mcp-main ফোল্ডার খুলুন

2. claude-talk-to-figma-mcp.mcpb ফাইলে ডাবল-ক্লিক করুন

3. Claude Desktop খুলে ইনস্টলের অনুমতি চাইবে → Install চাপুন (আগে থেকে থাকলে Replace)

4. Figma personal access token চাইলে → খালি রেখে Continue চাপুন। এটা শুধু কমান্ড টুলের জন্য, পরে দিলেও চলবে (ধাপ ৭)

5. Claude Desktop পুরো বন্ধ করুন: Cmd + Q চাপুন (লাল × চাপলে পুরো বন্ধ হয় না), তারপর আবার খুলুন

ডাবল-ক্লিকে কিছু না হলে: Claude Desktop → Settings → Extensions → .mcpb ফাইলটা টেনে এনে ওই পেজে ছেড়ে দিন।

✅ যাচাই: Claude Desktop → Settings → Extensions-এ Claude Talk to Figma দেখা যাচ্ছে এবং চালু আছে।

❓ ফাইলটা অন্য কোনো অ্যাপে খুলে গেলে: ফাইলে রাইট-ক্লিক → Open With → Claude।

ধাপ ৫: Figma-তে প্লাগইন ইনস্টল করুন

1. Figma Desktop অ্যাপ খুলুন, যেকোনো ডিজাইন ফাইল খুলুন

2. উপরে বাঁ কোণে Figma লোগো ("F" আইকন) → Plugins → Development → Import plugin from manifest…

3. এই পথে যান:

   Documents → claude-talk-to-figma-mcp-main → src → claude_mcp_plugin → manifest.json

4. manifest.json সিলেক্ট করে Open চাপুন

💡 src ফোল্ডার খুঁজে না পেলে ফাইল পিকারে Cmd + Shift + G চাপুন আর পেস্ট করুন: ~/Documents/claude-talk-to-figma-mcp-main/src/claude_mcp_plugin

✅ যাচাই: Plugins → Development-এ Claude Talk to Figma দেখা যাচ্ছে। এটা জীবনে একবারই করতে হয়।

ধাপ ৬: চালু করুন (প্রতিদিনের কাজ)

৬ক. ব্রিজ সার্ভার চালু করুন

Terminal খুলে চালান:

cd ~/Documents/claude-talk-to-figma-mcp-main
npm run socket

এমন লেখা আসবে:

Claude to Figma WebSocket server running on port 3055

🚨 এই Terminal উইন্ডো খোলা রাখুন। বন্ধ করলে বা Ctrl + C চাপলে ব্রিজ বন্ধ হয়ে যাবে আর Claude Figma হারাবে। উইন্ডোটা শুধু একপাশে সরিয়ে রাখুন।

💡 চালু আছে কিনা দেখতে ব্রাউজারে খুলুন: http://localhost:3055/status

৬খ. Figma-তে প্লাগইন খুলুন

আপনার Figma ফাইলে: Plugins → Development → Claude Talk to Figma

একটা ছোট প্যানেল খুলবে। সেখানে সবুজ বক্সে একটা channel ID দেখাবে, যেমন a4f9c2।

• Connect বাটন দেখালে সেটায় ক্লিক করুন।

• ID-টার উপর ক্লিক করলে পুরো বার্তা Connect to Figma, channel … কপি হয়ে যায়।

⚠️ প্লাগইন যতবার খুলবেন, ID ততবার বদলাবে। পুরোনো ID কখনো ব্যবহার করবেন না।

৬গ. Claude-কে কানেক্ট করুন

Claude Desktop-এ লিখুন, তবে a4f9c2-এর জায়গায় আপনার নিজের ID দিন:

Connect to Figma, channel a4f9c2

তারপর Figma-তে যেকোনো লেয়ার সিলেক্ট করে জিজ্ঞেস করুন:

What's currently selected in Figma?

Claude সেই লেয়ারের বর্ণনা দিলে সেটআপ সম্পূর্ণ। 🎉

ধাপ ৭ (ঐচ্ছিক): Figma কমেন্ট টুল

শুধু যদি চান Claude Figma-র কমেন্ট পড়ুক ও উত্তর দিক। বাকি সব এটা ছাড়াই কাজ করে।

1. Figma: আপনার ছবি → Settings → Security → Personal access tokens → Generate new token

2. এই দুটো scope চালু করুন: files:read আর file_comments:write

3. টোকেনটা সাথে সাথে কপি করুন (Figma একবারই দেখায়), এটা figd_ দিয়ে শুরু হয়

4. Claude Desktop → Settings → Extensions → Claude Talk to Figma → টোকেন পেস্ট করুন

5. Cmd + Q দিয়ে Claude বন্ধ করে আবার খুলুন

🔒 এই টোকেন দিয়ে আপনার অ্যাকাউন্টের সব ফাইল পড়া যায়। কখনো কারো সাথে শেয়ার করবেন না, চ্যাটে পেস্ট করবেন না।

📅 প্রথমবারের পর প্রতিদিন

সেটআপ স্থায়ী। প্রতিদিন শুধু তিনটি কাজ:

cd ~/Documents/claude-talk-to-figma-mcp-main && npm run socket

1. ✅ উপরের কমান্ড চালান (Terminal খোলা রাখুন)

2. ✅ Figma → Plugins → Development → Claude Talk to Figma → নতুন channel ID কপি করুন

3. ✅ Claude-কে লিখুন: Connect to Figma, channel তারপর আপনার ID

🧹 লেয়ার অপটিমাইজ ও Grid-এ রূপান্তর

অগোছালো লেয়ার পরিষ্কার করে (খালি ফ্রেম, অকেজো গ্রুপ, Frame > Frame > Card-এর মতো ডাবল নেস্টিং) আর কার্ডের সারিকে আসল Figma Grid-এ রূপান্তর করে, ডিজাইন দেখতে একটুও না বদলে।

কীভাবে ব্যবহার করবেন

1. Figma-তে একটা সেকশন বা ফ্রেম সিলেক্ট করুন, যেমন # Work Process। একসাথে পুরো পেজ সিলেক্ট করবেন না।

2. Claude-কে লিখুন:

   Optimize the layers of the selected section

3. Claude আগে শুধু স্ক্যান করবে (কিছুই বদলাবে না), তারপর যেখানে আপনার সিদ্ধান্ত লাগবে সেখানে জিজ্ঞেস করবে:

   Claude যা জিজ্ঞেস করবে	এর মানে	আপনার উত্তর
   "N টি হিডেন লেয়ার পাওয়া গেছে, রিমুভ করবেন?"	হিডেন লেয়ার হয়তো আপনি ইচ্ছে করে রেখেছেন	মুছতে হ্যাঁ, রাখতে না
   ""Card"-এ প্রোটোটাইপ ইন্টারঅ্যাকশন আছে, রিমুভ করবেন?"	মুছলে প্রোটোটাইপ, ইফেক্ট, এক্সপোর্ট বা মাস্ক নষ্ট হতে পারে	প্রতিটির জন্য আলাদা সিদ্ধান্ত
   ""# Work Process" ৪-কলাম Grid হতে পারে, রূপান্তর করবেন?"	হেডিং আর কার্ডগুলো সরাসরি Grid-এর ভেতরে বসবে, অপ্রয়োজনীয় র‍্যাপার সরে যাবে	রূপান্তর করতে হ্যাঁ

4. Claude শুধু আপনার অনুমতি দেওয়া কাজগুলোই করবে, আর কী বদলেছে জানাবে।

নিজে থেকে যা করে (জিজ্ঞেস না করেই)

• খালি ও শূন্য-মাপের লেয়ার সরায়

• অকেজো র‍্যাপার ফ্রেম সরায়: যার ভেতরে একটাই চাইল্ড হুবহু সমান মাপের, কোনো প্যাডিং, fill, stroke বা clip নেই

• র‍্যাপারের Fill সাইজিং চাইল্ডকে দিয়ে দেয়, তাই লেআউট হুবহু একই থাকে

যা কখনো করে না

• আপনার "হ্যাঁ" ছাড়া হিডেন লেয়ার, বা প্রোটোটাইপ, ইফেক্ট, এক্সপোর্ট সেটিং বা মাস্ক থাকা লেয়ার মোছে না

• মেইন কম্পোনেন্ট, কম্পোনেন্ট প্রপার্টি বা ভ্যারিয়েন্ট লেয়ার কখনো মোছে না

• লেখা, ফন্ট, রং, স্পেসিং ভ্যালু বা ভেরিয়েবল বদলায় না

• কম্পোনেন্ট ইনস্ট্যান্সের ভেতরে হাত দেয় না

Grid রূপান্তর কেন নিরাপদ

• কলাম সংখ্যা ডিজাইন থেকেই নেয়: ৪টি সমান কার্ড মানে ৪টি সমান কলাম (repeat(4, 1fr))।

• গ্যাপ আর প্যাডিং তাদের ভেরিয়েবল সহ থাকে।

• রূপান্তরের পর প্লাগইন প্রতিটি হেডিং ও কার্ডের পজিশন মেপে দেখে। ১px-এর বেশি নড়লে বা Figma কোনো ধাপ মানতে না চাইলে রূপান্তর বাতিল করে আগের অবস্থায় ফিরিয়ে দেয় আর কারণ জানায়। প্রতিটি রূপান্তর একবার Cmd + Z চাপলেই ফেরানো যায়।

• শুধু তখনই প্রস্তাব করে যখন Grid হুবহু একই রকম দেখাতে পারবে: একটা হেডিং, সমান চওড়ার কার্ডের একটা সারি, সারিতে প্যাডিং বা ব্যাকগ্রাউন্ড নেই।

⚠️ Grid রূপান্তর না হলে নিজে ungroup করে "ঠিক" করতে যাবেন না। Auto Layout সারি ungroup করলে কার্ডগুলো একটার নিচে আরেকটা চলে যায়। হাতে আবার সাজালে ফ্রেমটা fixed পজিশনের, লেআউটহীন হয়ে যায়: দেখতে ঠিক, কিন্তু আর রেসপন্সিভ থাকে না। বরং Claude যে কারণ জানিয়েছে সেটা দেখুন।

🌐 HTML ফাইল বা ওয়েবসাইট থেকে Figma ডিজাইন

একটা ওয়েব পেজকে Figma ডিজাইনে রূপান্তর করে, দেখতে হুবহু পেজের মতো: প্রতিটি সেকশন, লেখা, ছবি আর আইকন সহ। ডিজাইনটা আপনার ফাইলের নিজস্ব স্টাইল ও ভেরিয়েবলের সাথে যুক্ত থাকে, আর লেয়ার থাকে পরিষ্কার ও কম নেস্টেড।

কীভাবে ব্যবহার করবেন

1. Figma-তে সেই ফাইলটি খুলুন যার ডিজাইন সিস্টেম (কালার ভেরিয়েবল, টেক্সট স্টাইল, স্পেসিং টোকেন) ব্যবহার করতে চান।

2. ওয়েবসাইট বা HTML পেজের পুরো পেজের একটা স্ক্রিনশট নিয়ে Claude-কে দিন। শেষে Claude এটার সাথেই ফলাফল মিলিয়ে দেখবে।

3. Claude-কে লিখুন:

   Convert https://example.com to Figma

   Convert /Users/YOUR_NAME/Desktop/page.html to Figma

   💡 কম্পিউটারের ফাইল হলে পুরো path দিতে হবে, আর ফাইলটা Claude Desktop যে কম্পিউটারে চলছে সেখানেই থাকতে হবে। Mac-এ path পেতে: Finder-এ ফাইল সিলেক্ট করুন → Option চেপে ধরে রাইট-ক্লিক → Copy "page.html" as Pathname।

4. Claude এই ধাপগুলোতে কাজ করবে আর জানাবে কী করছে:

   ধাপ	কী হয়
   ১. বিশ্লেষণ	পেজ আর তার CSS পড়ে: সেকশন, লেখা, কালার, ফন্ট, স্পেসিং, radius, প্রতিটি ছবি ও আইকন, আর কোন অংশ গ্রিড বা সারি/কলাম
   ২. মিলিয়ে দেখা	প্রতিটি ভ্যালু আপনার ডিজাইন সিস্টেমের সাথে মেলায়: সিস্টেম থেকে ব্যবহার / কাছাকাছি কিন্তু হুবহু না / সিস্টেমে নেই
   ৩. তৈরি	যেখানে হুবহু মেলে সেখানে আপনার ভেরিয়েবল ও টেক্সট স্টাইল বসায়; বাকিগুলো পেজের নিজের ভ্যালু দিয়ে তৈরি করে। প্রতিটি ছবি ও আইকন বসায়। প্রতিটি অংশে Grid বা Auto Layout বেছে নেয় (নিচের টেবিল)
   ৪. কম্পোনেন্ট	যে জিনিস ২ বা তার বেশি বার আসে আর আপনার ফাইলে যার হুবহু কম্পোনেন্ট নেই, সেটা পেজের পাশে Components — from HTML নামের ফ্রেমে নতুন কম্পোনেন্ট হিসেবে তৈরি হয়, আর পেজে তার instance বসে। একবার আসা জিনিস সাধারণ লেয়ার হিসেবেই থাকে
   ৫. Import Notes	ডিজাইনের পাশে একটা ফ্রেম, যেখানে লেখা থাকে কী আপনার ডিজাইন সিস্টেমে ছিল না, কোন নতুন কম্পোনেন্ট তৈরি হয়েছে, আর কোনো কিছু হুবহু করা না গেলে সেটা
   ৬. মিলিয়ে দেখা	ফলাফল এক্সপোর্ট করে আপনার স্ক্রিনশটের সাথে মেলায়, পার্থক্য না থাকা পর্যন্ত ঠিক করে; তারপর লেয়ার স্ক্যান চালায়, কিছু মোছার আগে জিজ্ঞেস করে

যে নিয়ম মেনে চলে

• হুবহু। কিছু বাদ যায় না, কিছু যোগ হয় না, কোনো স্টাইল বদলানো বা সরল করা হয় না। কোনো কিছু সত্যিই তৈরি করা না গেলে Claude আন্দাজে কাছাকাছি বানায় না, Import Notes-এ জানিয়ে দেয়।

• আপনার স্টাইল গাইডের সাথে যুক্ত। যে কালার, টেক্সট স্টাইল, স্পেসিং বা radius আপনার ডিজাইন সিস্টেমে আছে, সেটা ভ্যালু টাইপ করে নয়, টোকেনের সাথে যুক্ত করে বসানো হয়। "কাছাকাছি" স্টাইল বা কম্পোনেন্ট ব্যবহার করা হয় না, কারণ তাতে ডিজাইন বদলে যায়।

• নতুন ভেরিয়েবল বা স্টাইল তৈরি হয় না। নতুন তৈরি হয় শুধু বারবার আসা জিনিসের কম্পোনেন্ট।

Grid নাকি Auto Layout?

জেনে রাখুন

• ছবি প্লাগইনের সার্ভার নিজেই ডাউনলোড করে (place_html_image) আর হুবহু মাপে বসায়, ওয়েবসাইট থেকে হোক বা লোকাল .html পেজের পাশের ফাইল থেকে। আইকন (inline SVG) ভেক্টর হিসেবে বসে, আইকন স্প্রাইট থেকে আসা আইকনও। কোনো ছবি আনা না গেলে তার হুবহু মাপের ফ্রেম Image-Missing-… নামে থেকে যায়, তাই লেআউট সরে যায় না।

• এটা পেজের HTML ও CSS পড়ে, ব্রাউজারে চালিয়ে দেখে না। যে পেজ লোড হওয়ার পর JavaScript দিয়ে কনটেন্ট বানায়, সেটা অসম্পূর্ণ আসতে পারে। তখন Chrome-এ পেজ খুলে File → Save Page As… → Webpage, Complete দিয়ে সেভ করুন, তারপর সেই .html ফাইল দিন।

• লগইন লাগে এমন পেজ পড়া যায় না। উপরের মতো সেভ করে দিন।

• ফন্ট আপনার কম্পিউটারে ইনস্টল থাকতে হবে, তবেই Figma ব্যবহার করতে পারবে।

🔄 নতুন ভার্সনে আপডেট করবেন যেভাবে

এই রিপোজিটরিতে নতুন ফিচার এলে (প্রায় ৩ মিনিট):

cd ~/Documents/claude-talk-to-figma-mcp-main
git pull
npm install
npm run build
npx dxt pack . claude-talk-to-figma-mcp.mcpb

তারপর:

1. নতুন claude-talk-to-figma-mcp.mcpb-এ ডাবল-ক্লিক → Install / Replace

2. Claude Desktop পুরো বন্ধ করুন (Cmd + Q), তারপর আবার খুলুন

3. ব্রিজ চলা Terminal-এ Ctrl + C চাপুন, তারপর আবার npm run socket চালান

4. Figma-তে প্লাগইন বন্ধ করে আবার খুলুন (তাহলে নতুন কোড লোড হবে), নতুন channel ID দিয়ে কানেক্ট করুন

🔑 "কিছুই বদলায়নি" মনে হওয়ার ১ নম্বর কারণ ১ বা ২ নম্বর ধাপ বাদ দেওয়া। আবার ইনস্টল করে রিস্টার্ট না করা পর্যন্ত Claude Desktop পুরোনো এক্সটেনশনই চালায়। Settings-এ ভার্সন নম্বর নাও বদলাতে পারে, তাই সেটা দেখে বিচার করবেন না।

🆘 সমস্যা ও সমাধান

তবুও সমস্যা থাকলে TROUBLESHOOTING.md দেখুন অথবা GitHub-এ Issue খুলুন।

🎨 Local design library first

The plugin will not design from scratch when your file already answers the question. Before creating or modifying anything, it inspects the current file and reuses what's there.

One call, the whole system

get_design_system replaces four separate lookups and returns:

That last row is the part styles alone can't tell you. Most real files encode their spacing rhythm in usage rather than in named tokens, so "match the existing spacing" is unanswerable without it. You get output like:

── OBSERVED CONVENTIONS — match this rhythm ──────────────
  Padding values:  16 (×24), 32 (×8)
  Gap values:      24 (×6), 12 (×2)
  Corner radii:    8 (×6), 4 (×2)

Now the agent knows to use 16 and 8, not a plausible-looking 20 and 10.

The rule it follows

Loaded as the design_system_first prompt:

1. Reuse an existing component exactly when it solves the need

2. Reuse an existing variant when a suitable variation exists

3. Compose existing components when it can be built from current primitives

4. Extend the system when a new variant is genuinely required

5. Create something new only as a last resort

It also binds rather than hardcodes — apply_variable_to_node for colour, set_text_style_id for type, create_component_instance for components — and when editing, preserves variable bindings and avoids detaching instances.

The existing design_strategy prompt used to say "plan your layout, then create elements", which pulled the other way. It now opens by deferring to this rule and describes how to build only once you've confirmed the thing you need doesn't already exist.

Using it

Usually nothing to do — the agent calls it on its own. To be explicit:

"Check the design system first, then build the settings page"

"What components and tokens does this file already have?"

Components often live on a dedicated library page. If a scan comes back empty, widen it:

"Scan the whole document for components, not just this page"

📱 Responsive Website

Turn an approved desktop design into tablet and mobile versions — by adapting layout behaviour, not by shrinking the frame.

How it works: clone, then adapt

Responsive frames are produced by cloning the source and changing how the clone flows. That single choice is what makes the safety guarantees real rather than aspirational:

• component instances stay connected — nothing is detached

• variable and style bindings survive untouched

• copy is never rewritten, images never replaced

• the original desktop frame is never modified

Behaviour, not scaling

Each section is classified and given its own responsive behaviour:

Nothing is ever scaled proportionally like an image.

Breakpoints

Default design frames are 1440 → 768 → 320. Intermediate widths are handled by Auto Layout, fill/hug sizing and wrapping rather than by more frames.

An exact designer-specified width always overrides the defaults. Pass targetWidth with the breakpoint behaviour: an 834px Tablet is named and built at 834px, while a 390px Mobile is named and built at 390px. Existing 768px or 320px frames are kept separate and are not overwritten by a different width.

Breakpoints are processed separately. Generate and validate Tablet first; begin Mobile only in a later run after the designer confirms it.

Absolute-positioned layers are copied with the desktop frame and left completely unchanged. The responsive engine does not ungroup, restructure, detach, rebuild, convert, resize, rebind, rename, reorder, or optimize those subtrees. They are reported for manual designer adjustment even when they do not fit the new width.

Desktop spacing is the maximum reference for responsive output. Tablet and mobile gaps and padding may stay the same or decrease, but they are never allowed to increase accidentally. The final responsive pass compares each matched container with desktop after variable modes resolve and caps increases while preserving variable bindings.

QA runs at both 390px and 320px. A layout that survives 390 and breaks at 320 is not responsive.

The three tools

Preservation modes

• strict (default) — layout flow only; typography untouched

• balanced — allows minor layout restructuring; typography remains untouched

• flexible — allows larger restructuring

The automatic pass preserves linked text styles in every mode. If layout changes still leave an oversized heading unreadable, use only an existing responsive style/token from the same family; never invent or manually override type values.

Using it

"Analyze this page for responsive issues"

"Make this responsive"

"Make a Tablet version at 834px"

"Make a Mobile version at 390px"

"Check the mobile frame at 320"

What it flags rather than guesses

When no safe pattern exists, it applies the least destructive change and tells you — it does not guess confidently:

Warnings — manual review required:
  ⚠ Pricing Table (table): no safe automatic responsive pattern.
    Least-destructive adjustment applied; manual review required.
  ⚠ Header: no mobile navigation variant exists in the component set.
    The desktop link list was hidden to prevent overflow — a hamburger
    menu and open/close states still need to be added.

👀 Watch the AI work — live activity tracking

By default an AI agent works silently and you only see the finished result. Live activity tracking makes the work visible while it happens — what's running right now, what it just changed, and how long each step took.

There are four places to watch, each covering a different audience.

1. The plugin panel

Nothing to turn on. The plugin panel now shows a scrolling feed of every action with timestamps, durations and the names of the nodes touched, plus a status chip that reads create frame · 3s while work is in flight and Idle · 12 done when it isn't.

2. The web dashboard — http://localhost:3055/dashboard

Open that URL in any browser while the socket server is running. It streams live over Server-Sent Events and shows every connected channel, whether each is working, the queue depth, and the full activity log with search and filtering.

Useful when you want a big readable view on a second monitor instead of the narrow plugin panel.

3. On the Figma canvas — a live cursor, like a real collaborator

The two surfaces above are only visible to you. These make the work visible to anyone with the file open:

Toggle them at the bottom of the plugin panel, or just ask:

"Turn on the live cursor so I can watch you work"

"Turn on the live cursor and call it Orange Toolz"

How the live cursor works — and one honest limitation

A Figma plugin cannot move your real multiplayer cursor. That pointer is driven by your physical mouse and the Plugin API gives no way to write to it.

So this draws its own: a cursor arrow plus a label pill, built from ordinary Figma nodes. Because they are ordinary nodes, Figma's multiplayer sync broadcasts every position change to everyone in the file — which produces the same effect as watching a collaborator move around the canvas.

The label also carries the current action, so observers see not just where the agent is but what it's doing there:

  ↖ Claude — create frame

It glides between elements over ~300ms rather than teleporting, stays locked so nobody can drag it by accident, drops back to just the name after 4 seconds of quiet, and is removed automatically when the plugin closes.

⚠️ The live cursor and the canvas overlay both write real nodes into your document, so they show up in version history and the undo stack. That's why both are off by default. Node highlighting gives you a good deal of the collaborator visibility and changes nothing at all.

4. Ask Claude directly

Three tools are available to the agent:

"What have you changed so far?"

"Are you still working on that, and how long has it been running?"

Running a second server on another port

The socket server listens on 3055. Set SOCKET_PORT to run another alongside it — handy for testing without disturbing a live session:

SOCKET_PORT=3056 npm run socket

Point the MCP server at it with --port=3056.

⚡ Speed and cost

A Figma session is expensive for two reasons, and neither is the thinking: the tool list is re-sent on every single message, and every write is its own round trip. Four things in this plugin attack that directly.

1. Batch your writes — figma_batch

Building one section normally takes 20–40 separate tool calls, and each one is a full round trip. figma_batch runs them all in a single call:

[
  {"command": "create_frame",    "params": {"x": 0, "y": 0, "width": 1440, "height": 600, "name": "Hero", "parentId": "0:1"}},
  {"command": "set_auto_layout", "params": {"nodeId": "$0.id", "layoutMode": "VERTICAL", "itemSpacing": 24}},
  {"command": "create_text",     "params": {"text": "Headline", "parentId": "$0.id"}},
  {"command": "set_font_size",   "params": {"nodeId": "$last.id", "fontSize": 56}}
]

Ops run in order. $0.id refers to the first op's result and $last.id to the previous one, so a frame's ID can feed its children without a trip back to the model. stopOnError defaults to true; set it to false for independent work such as recolouring many unrelated nodes.

Ask the AI to load the efficient_execution prompt at the start of a session and it will batch by default.

2. Pick a tool profile

The tool list costs about 25,000 tokens on every message, whether or not any of those tools get used. A profile trims what is advertised:

Nothing is ever lost. A tool a profile withholds is still callable through figma_batch by name.

Set it in the extension's settings (Tool profile), or with the FIGMA_MCP_PROFILE environment variable for a manual install.

3. Repeated library reads are cached

get_design_system, get_styles, get_local_components, get_variables, get_document_info and get_pages are served from a short-lived cache, so the "check what already exists before creating" rule stops costing a round trip every time it fires. Any command that changes the document clears the cache immediately, so you never act on a stale read. Disable with FIGMA_MCP_CACHE=off.

4. Responses have a ceiling

One deep get_node_info on a large page could previously fill the context window by itself. Tool responses are now capped (~24,000 characters, roughly 6,000 tokens) and truncated with a note telling the AI to narrow the query. Adjust with the Maximum tool response size setting or FIGMA_MCP_MAX_RESPONSE_CHARS.

5. See what it cost — get_token_usage

Every Figma task spends context twice — once for the arguments the agent writes, and again for the result text, which the model re-reads on every later turn. The expensive calls are rarely the obvious ones: reading a deep node tree costs far more than creating a frame.

The server tallies both halves of every tool call and reports them, so a task can end with a plain statement of what it cost:

This task — ~18k tokens across 47 Figma tool calls in 2m 14s
  sent ~2.1k · received ~16k
  most expensive:
    get_node_info — 9×, ~11k tokens
    scan_text_nodes — 3×, ~3.4k tokens
    figma_batch — 12×, ~2.0k tokens
  (Estimated from payload size at ~4 chars/token. Covers Figma tool traffic only,
  not the rest of the conversation.)

Every tool result also carries a one-line running total:

[figma-usage: ~4.2k tokens over 12 calls this task — report this to the user when the task is done]

That footer is the part that makes this reliable. An instruction telling the agent to call a tool at the end of a task is only as good as its compliance, and a report nobody sees is the same as no feature — so the number rides along in every result instead. It costs about a dozen tokens per call. Turn it off with FIGMA_MCP_USAGE_FOOTER=off if you would rather rely on the tool alone.

The agent is instructed to call get_token_usage once at the end of a task and show you the result, so you get this without asking. You can also ask for it directly:

"How many tokens has that cost so far?"

Two limits worth knowing. The counts are estimated from payload size at ~4 chars/token, not produced by a tokenizer, so treat them as a close approximation rather than a bill. And an MCP server sits outside the model's context window: it can measure the traffic crossing this bridge, but not your system prompt, your messages, or the model's own reasoning. The figure is the cost of the Figma work, not of the conversation.

6. Per-chat totals — npm run tokens

get_token_usage measures the Figma bridge. It cannot measure the chat, because an MCP server sits outside the model's context window. Those numbers come from elsewhere: Claude Code writes one JSONL transcript per session under ~/.claude/projects/, and every assistant message in it carries the API's own usage block. scripts/chat-token-report.mjs sums them.

npm run tokens                 # this project's chats, newest first
npm run tokens -- --all        # every project
npm run tokens -- <session-id> # one chat, broken down

last active       turns    input  cache rd   output    total  chat
──────────────────────────────────────────────────────────────────
2026-09-07 17:00     70   147.5k     4.70M    40.8k    4.89M  add token reporting
2026-09-04 09:35      7    36.0k    299.8k     1.6k   337.4k  push to main branch

Read the cache rd column before the total one. Most of a long chat's tokens are cache reads — the same context re-sent each turn — and those are billed far below the base input rate, so the raw total badly overstates cost. For money rather than tokens, use /cost in Claude Code or the Anthropic Console.

In Claude Desktop there is no equivalent: it keeps no local transcript and exposes no token counter, so get_token_usage is the only per-task figure available there.

Also faster

scan_text_nodes and set_multiple_text_contents used to tint each text node orange and wait half a second for the tint to be visible — on a page with 60 text nodes that is 30 seconds of pure waiting, and it wrote to the document during what should have been a read. That highlighting is gone; live progress now comes from moving the selection instead, which touches nothing. scan_text_nodes also works in larger chunks, and the one-second pause between text-replacement chunks (which only existed to let the tint animate) is down to a short yield.

🧩 Skills

A skill is a vetted, step-by-step procedure for a recurring design job — "rename every layer semantically", "audit contrast", "build a pricing section". Written once, it produces the same quality every time instead of the AI working the job out from scratch and landing somewhere different each run.

Skills live in skills/ as Markdown files and are compiled into the extension at build time.

Using one

Two ways, both serving the same skill:

• Prompt picker — every skill is registered as an MCP prompt under its ID (Layer_Rename_v1), so it appears in Claude's prompt list.

• figma_skill tool — how the AI reaches one on its own mid-conversation:

  figma_skill()                                    → the catalogue
  figma_skill({query: "messy layer names"})        → best matches
  figma_skill({name: "Layer_Rename_v1"})           → full instructions

Writing one

Drop a Markdown file into your skills directory — ~/.figma-mcp/skills by default, or wherever FIGMA_MCP_SKILLS_DIR points. It is live on the next restart; no rebuild. A file placed there with the same ID as a built-in overrides it, so you can adapt a shipped skill without forking anything.

---
id: Audit_Contrast_v1
title: Contrast Auditor
description: >
  Checks text colour contrast across a frame and reports failures.
triggers:
  - check contrast
  - accessibility audit
uses:
  - get_node_info
  - export_node_as_image
---

# Contrast Auditor

1. Call `export_node_as_image` on the frame...

Naming: Category_Action_vN

The ID is not decoration — the registry reads it. Layer_Rename_v1 and Layer_Rename_v2 are the same skill at two versions, so the older one is retired automatically; Layer_Clean_v1 is a different skill in the same category. Category and Action are PascalCase, the version is v plus a whole number. A file that breaks the convention is rejected at startup with the reason printed in the log, and the rest keep working.

What the system checks

Self-repair, and its limits

Skills are often written against a different Figma MCP server, then name a tool that does not exist here — get_screenshot instead of export_node_as_image. The AI dutifully calls it and the step fails.

At startup, every skill is checked against the live tool set. When a name has a known one-for-one equivalent, the skill is rewritten with the correct name and saved as the next version (Audit_Contrast_v1 → Audit_Contrast_v2). The original stays on disk as the record of what changed. Turn this off with FIGMA_MCP_SKILL_AUTOREPAIR=off to review repairs instead of applying them.

What it will not do: repair a skill whose instructions are wrong — prose that produces bad designs, a missing step, a wrong order. Nothing here evaluates meaning, and a system that rewrites guidance it cannot judge would do more harm than the bug. Those failures are recorded against the skill and reported for a person to read. Substitutions are limited to a curated table of genuine equivalents; a tool with no real counterpart is reported, never swapped for something that behaves differently.

🆘 Troubleshooting common errors

Still stuck? See TROUBLESHOOTING.md, or open an issue.

🔧 Other AI tools (Cursor, Claude Code, Windsurf, VS Code…)

Steps 1, 2, 5 and 6 are identical for every tool — only Steps 3 and 4 are Claude-Desktop-specific. Other clients read a JSON config file instead of installing an extension.

⚠️ Don't use npx claude-talk-to-figma-mcp. That pulls the upstream package, which does not include the comment tools. This fork must be built from source.

Cursor

1. Cursor Settings → Tools & Integrations → New MCP Server (opens mcp.json)

2. Add this, replacing the path with your absolute path:

{
  "mcpServers": {
    "ClaudeTalkToFigma": {
      "command": "node",
      "args": ["/Users/YOUR_NAME/Documents/claude-talk-to-figma-mcp-main/dist/talk_to_figma_mcp/server.cjs"],
      "env": { "FIGMA_ACCESS_TOKEN": "figd_your_token_here" }
    }
  }
}

3. Save and restart Cursor

💡 To get the exact path, run pwd inside the project folder and paste the result.

🪟 Windows: double the backslashes — "C:\\Users\\You\\claude-talk-to-figma-mcp-main\\dist\\talk_to_figma_mcp\\server.cjs"

Claude Code

claude mcp add ClaudeTalkToFigma \
  --env FIGMA_ACCESS_TOKEN=figd_your_token_here \
  -- node ~/Documents/claude-talk-to-figma-mcp-main/dist/talk_to_figma_mcp/server.cjs

Check with claude mcp list, or /mcp inside Claude Code.

Everything else

Windsurf, Antigravity, VS Code + Copilot, Cline and Roo Code follow the same pattern with slightly different file locations — see the "Configure your Agentic Tool" chapter of the detailed installation guide.

🐳 Alternative: Using Docker

If you prefer Docker or need to run the WebSocket server in a team environment, see the Docker installation guide.

🤖 Multi-Agent & Parallel execution

This MCP server supports safe parallel execution out of the box, allowing multiple AI agents (e.g. Claude Code's sub-agents or team swarms) to work simultaneously on your Figma file without locking up the plugin. A built-in command queue processes requests sequentially on the server side, preventing the Figma API from timing out.

Note: Because multiple agents can modify the document simultaneously, relying on implicit page context is unsafe. As a result, stateful commands like set_current_page are blocked. All agents must explicitly provide the intended parentId parameter when executing any creation or structural modification command (e.g., create_frame, create_text).

(Special thanks to @mmabas77 for architecting and contributing this feature!)

🛠️ Capabilities

Design analysis

• Get document information, current selection, styles

• Scan text, audit components, export assets

Element creation

• Shapes, text, frames with full style control

• Clone, group, organize elements

Modification

• Colors, borders, corners, shadows

• Auto-layout, advanced typography

• Local components and team library components

Comments — see below

See complete command list.

💬 Comment tools

Read and reply to Figma review threads directly from your agent.

Figma's Plugin API has no access to comments — they aren't part of the document tree and are never exposed to plugins. So these tools take a second route: they call Figma's REST API directly. That has two practical consequences:

• They need a personal access token (every other tool does not).

• They work without the socket running and without join_channel.

No file URL required

fileKey is optional on every comment tool. Omit it and the server asks the connected plugin which file is open:

You: check all comments
→ reads the comments on whatever file you're looking at

Pass fileKey explicitly only to target a different file — which also works with no plugin channel connected.

Automatic resolution uses figma.fileKey, which requires the private plugin API. It's available for locally imported and organisation plugins (this project sets enablePrivatePluginApi: true) and undefined on public plugin builds. If unavailable you get an explicit message rather than a silent failure.

Setup

See Step 7 above for the click-by-click version. For non-Claude-Desktop clients, expose the token as FIGMA_ACCESS_TOKEN in the env block of your MCP config:

{
  "mcpServers": {
    "ClaudeTalkToFigma": {
      "command": "node",
      "args": ["/absolute/path/to/claude-talk-to-figma-mcp-main/dist/talk_to_figma_mcp/server.cjs"],
      "env": { "FIGMA_ACCESS_TOKEN": "figd_your_token_here" }
    }
  }
}

Restart your client and run check my Figma account to verify.

Full details and tuning options in the installation guide.

What you can ask

✅ "Check all comments"

✅ "Show me every unresolved comment I'm involved in across the team,
    and flag the ones waiting on my reply"

✅ "Read my open comments, look up the node each one is pinned to,
    and draft a reply explaining the fix"

✅ "Reply to all my threads from last week confirming they're addressed
    in v2 — dry run first"

Threads come back with author, pin location, resolved status, timestamps and the node id each comment is attached to — so you can hand that id straight to get_node_info and reason about what the feedback refers to.

📚 Documentation

• Detailed installation — Manual setup, Cursor, Windsurf and other IDEs

• Available commands — Complete tool reference

• Troubleshooting — Common errors and how to fix them

• Contributing — Architecture, testing, contribution guide

• Changelog — Version history

🙏 Credits

Based on cursor-talk-to-figma-mcp by Sonny Lazuardi. Adapted for Claude Desktop and extended with new tools by Xúlio Zé.

This fork adds the Figma REST comment tools and automatic file-key resolution, maintained by litoondev. For the original project, see arinspunk/claude-talk-to-figma-mcp.

If you want to know about all project contributions, you can visit the "Contributors" chapter of the contribution guide.

MIT License

📊 Project status

✅ Stable production - Tool ready for daily use in design and development teams

🆕 New — HTML / URL → Figma:

• Converts a web page or .html file into a Figma design that looks identical, images and icons included

• Binds your own variables and text styles; repeated elements without a component become new components beside the page

• Chooses Figma Grid or Auto Layout per container, and lists anything not in your design system in Import Notes

🆕 New — layer optimization:

• Scan → ask → apply: hidden and risky layers are removed only with your confirmation

• Double-nested Auto Layout wrappers collapsed without changing the design

• Heading + card rows converted to Figma Grid, verified to 1px and undone if anything moves

🆕 New in 1.2.0:

• Read and reply to Figma comments via the REST API

• Automatic file-key resolution — no pasting file URLs

• Token prompt built into the DXT/MCPB package

🚀 Under active development:

• Complete support for Figma Variables

• Enhanced export to Tailwind CSS/SwiftUI

Need something specific?

Propose new ones on GitHub Issues

For issues with the underlying MCP (not the comment tools), consider upstream instead.

Your feedback and contributions keep the project alive. ❤️