figma-mcp
Self-hosted MCP server providing tools for reading and editing Figma design files: retrieving design context as React + Tailwind reference code, node metadata, screenshots, variable definitions, FigJam content, exported assets (images/SVGs), design-system search over components, styles and variables, library usage and Dev Mode code links, plus running Plugin API JavaScript in the open file to create and modify nodes.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@figma-mcp pull the design context for node 12:34 so I can build it in React"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
figma-mcp
📘 Hướng dẫn tiếng Việt: HUONG-DAN.md covers step-by-step setup, how it works, features, limitations and troubleshooting.
A self-hosted MCP server for Figma with the same tools and parameters as the official Figma MCP server. It runs on your own machine with your own token.
Each tool name carries a figma_local_ prefix (figma_local_get_design_context, figma_local_use_figma, …). That way it can run next to the official Figma MCP or other Figma servers without two tools sharing a name. Prompts and skills written for the official tools still apply: the agent calls the prefixed version. To use the official names unprefixed, set FIGMA_TOOL_PREFIX to an empty string.
Reads go through the companion plugin first. When the "Figma MCP Bridge" plugin is open in the requested file, read tools get their data from the Plugin API and use none of your REST API quota. Otherwise they use the Figma REST API with a personal access token, and Figma desktop doesn't need to be open.
Writes (
use_figma) always go through the plugin. It runs Plugin API JavaScript in the open file and talks to the server over a local WebSocket.
MCP client (Claude Code, Claude Desktop, Cursor…)
│ stdio
▼
figma-mcp ──── ws://localhost:3850 ◄── "Figma MCP Bridge" plugin in Figma desktop (reads first, use_figma)
│
└──────── HTTPS ────► api.figma.com (reads when the plugin isn't open in that file)Plugin-first reads
Figma's REST API is rate-limited per token, and on free plans and view/collab seats the limit for file reads is very low. Once it's used up, Figma can block reads for days (429 … Retry after 397698s). Plugin-first reads avoid that:
Node data comes from the plugin's
exportAsync({ format: 'JSON_REST_V1' }). It returns the same JSON as the REST nodes endpoint, so code generation, metadata and variables behave the same either way.Screenshots, exports, SVGs and image fills are rendered by the plugin and saved under
FIGMA_ASSET_DIR. Tools then return a localfilepath where the REST path returns a temporaryurl.search_design_systemindexes the file's components, styles and variables (including variables from enabled libraries) inside the plugin.Fallback: if a plugin read fails for any reason other than "node not found", the tool falls back to REST, and if both fail the error names both causes. Every response reports its
source(pluginorrest).Keep the file visible. Figma desktop pauses rendering for a file in a background tab or a minimized window. Data reads still work, but screenshots and exports wait until the file is visible, so they time out after 25 seconds with a hint and then fall back to REST.
Still REST-only: library usage (
get_libraries) and dev resources (get_code_connect_map). When REST is unavailable,get_librariesreturns what the plugin can see.
Tools
Names below are shown without the figma_local_ prefix.
Tool | Backend | Notes |
| plugin → REST | React + Tailwind reference code with |
| plugin → REST | XML of layer types, names, positions and sizes. Without |
| plugin → REST | PNG capped by |
| plugin → REST |
|
| plugin → REST | FigJam content as XML (stickies, shapes, connectors with from/to, sections, text) plus an image. |
| plugin → REST |
|
| plugin → REST, dev resources via REST | Maps component instances to the code links attached to their main components as Dev Mode dev resources. |
| plugin → REST | Searches components, styles and variables in the file, plus your team's libraries when |
| REST (partial via plugin) | Libraries the file uses, what the file itself publishes, and (with |
| plugin | Runs JavaScript with the |
| REST + plugin | The authenticated user, the auth method, the tool prefix, the bridge mode, and which files have the plugin open (with page and selection). |
fileKey also accepts a pasted figma.com URL, and nodeId accepts both 1:2 and 1-2. Branch URLs resolve to the branch key.
Differences from the official server
The official server uses Figma internals that the public API does not expose, so some behavior is approximated:
Code generation is this project's own React + Tailwind generator. It covers auto layout (flex, wrap, grid), FIXED/HUG/FILL sizing, absolute children with constraints, fills, gradients, image fills, borders, radii, shadows, blurs, blend modes, text styles with per-range overrides, and icons exported as SVG. Expect it to differ from Figma's own output.
Variables: the REST variables endpoint works only on Enterprise plans. On other plans, variable names come from the plugin. Without either one, bound variables are listed as unresolved IDs and raw values are used.
Code Connect: mappings published with the Figma Code Connect CLI are not readable through the public API. This server reads Dev Mode dev resources instead, so link your code components there.
Libraries: the API does not say which libraries are switched on for a file.
get_librariesreports the libraries the file actually uses.Not included:
create_session,create_new_file,generate_figma_design/html_to_figma,upload_assets,add_code_connect_map,generate_diagram, Figma Make files, and the official skill resources. Most of what these do can be done throughuse_figma.
Related MCP server: Fimake
Setup
1. Build
git clone https://github.com/deniahc566/FigmaMCP-LocalBridge.gitcd FigmaMCP-LocalBridgenpm installnpm run buildRequires Node.js 20 or newer.
2. Create a personal access token
In Figma, go to Settings → Security → Personal access tokens and generate a token with these scopes:
Scope | Used by |
| everything that reads a file |
|
|
|
|
| published components and styles of a file |
| resolving library components ( |
| team library search (only with |
| REST variables (Enterprise only, optional) |
3. Register the server with your client
Claude Code:
claude mcp add figma-local -e FIGMA_ACCESS_TOKEN=figd_your_token -- node /absolute/path/to/figma-mcp/dist/index.jsTo keep the token out of the client config, copy .env.example to .env, put the token there, and start the server with Node's --env-file flag (Node 20.6+):
claude mcp add --scope user figma-local -- node --env-file=/absolute/path/to/figma-mcp/.env /absolute/path/to/figma-mcp/dist/index.jsClaude Desktop, Cursor and other JSON-configured clients:
{
"mcpServers": {
"figma-local": {
"command": "node",
"args": ["/absolute/path/to/figma-mcp/dist/index.js"],
"env": {
"FIGMA_ACCESS_TOKEN": "figd_your_token",
"FIGMA_TEAM_ID": "optional-team-id"
}
}
}
}This server can stay connected alongside the official Figma MCP and figma-mcp-go: its tools all start with figma_local_, so none of the names collide. To send the agent to this server, mention it by name (for example, "use the figma_local tools").
4. Install the companion plugin (needed for use_figma)
Open the Figma desktop app.
Go to Plugins → Development → Import plugin from manifest… and choose
plugin/manifest.json.In the file you want to edit, run Plugins → Development → Figma MCP Bridge. The plugin window shows "Connected to 1 MCP server" once the server is found. Keep the window open while you work.
The plugin connects to every port in localhost:3850–3854. Each running server instance (for example, one per Claude Code session) takes the first free port, so several sessions can use the same plugin window.
When all five ports are taken, a new instance joins one of the listening instances as a relay: its reads and use_figma calls go through that instance's port to the plugin. When the instance it relays through shuts down, the relay takes the freed port, or joins another instance. whoami reports the bridge mode (host, relay, or waiting) and the relayPort. Only instances from this build can relay. An instance from an older build holds its port without answering, so while older sessions hold all five ports, a new instance waits and retries in the background. Restart those sessions to update them.
Configuration
Variable | Default | Purpose |
| — | Personal access token (sent as |
| — | OAuth token (sent as |
| — | Turns on team library search and the "available to add" list. The team ID is in the team page URL: |
| system temp | Where screenshots and assets rendered by the plugin are saved, one folder per file key. |
|
| Prepended to every tool name. Set it to an empty string for the official names, or to your own prefix (letters, digits, |
|
| Set to |
|
| Interface the bridge binds to. |
|
| Ports to try. If you change them, update |
|
| Shared secret that relaying instances present. It is created on first use. Every instance must use the same file. |
|
| Default timeout for |
|
| REST base URL (the tests point it at a mock). |
Security
The bridge listens only on loopback. It refuses WebSocket connections that carry a real web origin, so a browser tab cannot pose as the plugin. Figma plugin iframes report the opaque origin
null.A relaying instance must present the secret from
FIGMA_BRIDGE_SECRET_FILE, which is readable only by your account. Other users on the same machine cannot send code to your plugin through the loopback port.use_figmaruns any code the agent sends, with full edit rights in the open file. Each call is a single undo step, but review what the agent is doing in files that matter.The token stays in the server process. The plugin never sees it.
Development
npm testThe test suite builds the project and then runs:
test/codegen.test.mjs: URL parsing, layout/text/asset/variable code generation, and metadata XML against a fixture card design.test/e2e.test.mjs: starts the real server over stdio against a mock Figma REST API, and runs the realplugin/code.jsagainst a mockedfigmaglobal, relayed over the bridge WebSocket the same wayplugin/ui.htmldoes. It checks that reads make no REST file calls while the plugin is open, and that they fall back to REST when the plugin can't read. A second instance on the same port checks the relay: calls through it reach the plugin, a peer without the secret is refused, and the relay takes over the port when the first instance shuts down.test/naming.test.mjs: the tool-name prefix (default, empty, custom, invalid) and the prefixed names inside descriptions and instructions.
Source layout:
src/
index.ts stdio entry point, starts the bridge
server.ts McpServer + instructions
config.ts environment configuration
figma/reader.ts plugin-first reads (JSON_REST_V1 export, renders) with REST fallback
figma/rest.ts REST client (retries on 429/5xx, short-lived caches)
figma/variables.ts variable resolution: plugin → REST (Enterprise) → unresolved
bridge/server.ts WebSocket bridge to the plugin, and the relay between instances
codegen/ React + Tailwind generator, XML metadata, paint helpers
tools/ tool definitions, grouped by area
plugin/ companion Figma plugin (manifest, main thread, UI relay)
examples/ call-tool.mjs: call a tool from a script, without an agentLicense
Available Tools
11 toolsfigma_local_download_assetsDownload assetsARead-only
Download assets for a single node: export (an exported image of the whole node), rawImages (original uploaded images used as fills in the subtree, capped at 20, each with its real format) and svgAssets (SVGs for vector layers such as icons and logos, capped at 20). When defaultFormat/defaultScale are given they override the export settings configured on the node; otherwise the node's export settings are used if present, else png at scale 1. Pass them only when the user asks for a specific format or size. Each asset has a temporary url (download promptly) or, when the companion plugin rendered it, a local file path.
Inputs: nodeId (required), fileKey (required), defaultScale, defaultFormat.
figma_local_get_code_connect_mapGet Code Connect mapARead-only
Get a mapping of {[nodeId]: {codeConnectSrc, codeConnectName}} for the component instances in a node, e.g. {'1:2': {codeConnectSrc: 'https://github.com/foo/components/Button.tsx', codeConnectName: 'Button'}}. This server reads the code links attached to components as Dev Mode dev resources (Figma's public API does not expose CLI-published Code Connect files). Extract nodeId and fileKey from the URL; do not pass an empty or guessed nodeId.
Inputs: nodeId (required), fileKey (required), codeConnectLabel.
figma_local_get_design_contextGet design contextARead-only
Get design context for a Figma node — the primary tool for design-to-code workflows. Returns React + Tailwind reference code, asset download URLs, the design tokens and components used, and a screenshot of the node. The code is a reference: adapt it to the target project's components, design tokens and conventions. Use the nodeId parameter to specify a node id and the fileKey parameter to specify the file key. If given the URL https://figma.com/design/:fileKey/:fileName?node-id=1-2, the nodeId is 1:2 and the fileKey is :fileKey. If the URL does not include node-id, ask the user for a node-specific URL; do not pass an empty or guessed nodeId. For branch URLs (https://figma.com/design/:fileKey/branch/:branchKey/:fileName) use the branchKey as the fileKey.
Inputs: nodeId (required), fileKey (required), forceCode, clientLanguages, +3 more.
figma_local_get_figjamGet FigJamARead-only
Get the content of a FigJam board node as XML: stickies, shapes, connectors (with from/to node IDs), sections, text and tables, including their text and colors. If no node id is provided, use 0:1. Extract nodeId and fileKey from the URL, e.g. https://figma.com/board/:fileKey/:fileName?node-id=1-2. Only for FigJam files (URL path /board/).
Inputs: nodeId (required), fileKey (required), clientLanguages, clientFrameworks, +1 more.
figma_local_get_librariesGet librariesARead-only
Get the design libraries associated with a Figma file. Returns (1) libraries in use by the file (the libraries its component instances and styles come from) and (2) libraries available to add (the team's published libraries, when FIGMA_TEAM_ID is set). Each library has a name and library key (the library file key). The available list is paginated: pass libraries_available_to_add_next_offset back as offset. Use library keys to scope figma_local_search_design_system via includeLibraryKeys.
Inputs: fileKey (required), offset.
figma_local_get_metadataGet metadataARead-only
IMPORTANT: Always prefer figma_local_get_design_context. Get metadata for a node or page in XML format: node IDs, layer types, names, positions and sizes only. Useful for an overview of the structure; call figma_local_get_design_context on the node IDs it contains. The nodeId can also be a page id (e.g. 0:1). When nodeId is omitted, returns the top-level pages of the document instead. If the URL includes node-id, pass it as nodeId; otherwise omit nodeId. For branch URLs use the branchKey as the fileKey.
Inputs: fileKey (required), nodeId, clientLanguages, clientFrameworks.
figma_local_get_screenshotGet screenshotARead-only
Generate a screenshot for a node. Works on design files, FigJam boards and Slides. maxDimension (default 1024) caps the longer edge of the PNG; the metadata includes the rendered width/height and the node's original_width/original_height. By default returns a short-lived URL plus curl instructions, or a local file path when the companion plugin rendered it; both cost far fewer tokens than an inline image. Set enableBase64Response: true only when you cannot fetch URLs or read files. nodeId and fileKey are required; extract them from the URL (node-id=1-2 -> 1:2). For branch URLs use the branchKey as the fileKey.
Inputs: nodeId (required), fileKey (required), contentsOnly, maxDimension, +3 more.
figma_local_get_variable_defsGet variable definitionsARead-only
Get the variables and styles used by a node and its children, e.g. {'icon/default/secondary': '#949494'}. Variables are reusable values for colors, sizes, spacing and fonts. Extract nodeId from the URL (node-id=1-2 -> 1:2); do not pass an empty or guessed nodeId. Variable names resolve through the companion plugin when it is running in the file, or through the REST variables API on Enterprise plans. For branch URLs use the branchKey as the fileKey.
Inputs: nodeId (required), fileKey (required), clientLanguages, clientFrameworks.
figma_local_search_design_systemSearch design systemARead-only
Search for design system assets (components, variables and styles) in the file and in the team's libraries. Pass queries as an array of objects, each with entity ("component", "variable" or "style") and a string query, e.g. {"fileKey":"","queries":[{"entity":"component","query":"button"},{"entity":"variable","query":"surface"}]}. Combine the searches the task needs in one call. Results come back in a results array in the same order as queries.
Inputs: fileKey (required), queries (required), limit, disableCodeConnect, +1 more.
figma_local_use_figmaUse FigmaADestructive
Create, edit, inspect or sync anything in a Figma file by running JavaScript against the Figma Plugin API: frames, components, variants, variables, styles, text, auto layout, images and whole screens. Works in design files and FigJam boards. Requires the companion "Figma MCP Bridge" plugin to be running in the target file in the Figma desktop app. The code runs as the body of an async function with figma in scope. Use return to send JSON-serializable data back (nodes are returned as {id, name, type}; bytes from exportAsync come back as images). A single expression is returned automatically. console.log output is captured. GOTCHAS: the plugin uses dynamic page loading, so use async APIs: await figma.getNodeByIdAsync(id), await figma.setCurrentPageAsync(page), await page.loadAsync() before reading another page. Call await figma.loadFontAsync({family, style}) before setting text; the Inter style is "Semi Bold", not "SemiBold". Append new nodes to a parent and position them, and return the IDs of what you created. Each call is committed as one undo step.
Inputs: code (required), fileKey (required), description (required), timeoutMs.
figma_local_whoamiWho am IARead-only
Returns the authenticated Figma user (handle, email, id), how this server authenticates, the tool name prefix, and the status of the companion plugin bridge (which files have the plugin open, their current page and selection). Use this tool when you hit file access or permission errors, rate limits, or when figma_local_use_figma cannot find the plugin.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Most tools have clearly distinct purposes: design context, metadata, screenshot, variables, libraries, FigJam, assets, code connect, and design-system search. There is some conceptual overlap between get_design_context, get_screenshot, get_metadata, and download_assets, but the descriptions provide enough guidance to choose correctly. whoami and use_figma are also clearly differentiated.
All tools use snake_case and a shared figma_local_ prefix, with mostly predictable verb_noun patterns such as get_design_context, download_assets, and search_design_system. The main minor deviation is figma_local_whoami, which is idiomatic but does not follow the verb_noun pattern. use_figma is also slightly generic but still consistent with the prefix style.
The server exposes 11 tools, which is well within the typical 3-15 range for a focused MCP server. Each tool appears to earn its place by covering a distinct capability area such as metadata, assets, variables, search, or editing. There is no obvious bloat or missing operational category.
The tool surface comprehensively covers Figma design and FigJam workflows: authentication/diagnostics, design context extraction, metadata and screenshots, variables and styles, libraries, asset downloads, Code Connect mapping, design-system search, and plugin-based read/write via JavaScript. This spans both read-only inspection and editing, with no obvious dead ends for the stated purpose.
Maintenance
Related MCP Connectors
The Figma MCP server brings Figma design context directly into your AI workflow.
Serves your design system and coding standards to coding agents, so they stop guessing.
Give AI agents your deeepSpace design system: components, tokens, styles and code mappings.
Access and maintain design system docs, tokens, components, skills, and contexts across any project.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI agents to interact with Figma to create, read, and manage designs using the Figma REST API and a dedicated plugin. It supports advanced features like UI generation from text, webpage reconstruction in Figma, and design token synchronization with codebases.20MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to read, create, edit, and organize Figma documents directly through a local plugin bridge, without needing a Figma AI subscription.3Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to read, inspect, and edit Figma files through a Model Context Protocol server with 107 tools, visual snapshots, fidelity tools, and optional REST API access.33 npmMIT
- AlicenseAqualityBmaintenanceEnables AI coding agents to read and edit the file currently open in Figma Desktop through a local development plugin, supporting node inspection, JSON/image exports, and arbitrary Plugin API scripts without REST API rate limits.711 npmMIT