Skip to content

About

Local MCP server + Figma dev plugin that lets Claude, Codex and GitHub Copilot read and edit the file open in Figma Desktop. Works on a View seat, no rate limits.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Figma Bridge MCP

A local MCP server that lets AI coding agents (Claude, Codex, GitHub Copilot) read and edit the file you have open in Figma Desktop. It talks to Figma through a small development plugin instead of the REST API or Figma's hosted MCP, so:

  • it works on a View / Starter seat (the hosted MCP gives a handful of calls a month there),
  • there are no rate limits and no response truncation,
  • the agent can write to the file, not only read it (via figma_run_script).

How Figma Bridge works

AI agent ──stdio──> figma-bridge (server.js) ──ws://127.0.0.1:3055──> plugin/ui.html ──postMessage──> plugin/code.js (Plugin API)

The agent starts the server (npx -y @maxsbond/figma-bridge) as a stdio MCP server. The server opens a WebSocket on 127.0.0.1:3055 and waits. The "Figma Bridge" plugin, running in Figma Desktop, connects to it and executes each request with the Plugin API in the open file.

Requirements

  • Node.js 18 or newer (the LTS installer is fine)
  • Figma Desktop (the browser version can't reach localhost from a dev plugin)
  • Edit access to the file. Figma doesn't run plugins in view-only files; if you only have view access, duplicate the file to your drafts.

Quick install

Paste this into Claude Code, Codex, Copilot or any other agent that can run terminal commands. It sets up everything except the two clicks in Figma, and tells you what those are.

Install Figma Bridge (https://github.com/MaxsBond/figma-bridge) for me:
1. Add the MCP server to your own MCP config: command `npx`, args `["-y", "@maxsbond/figma-bridge"]`. If the config file already exists, merge the entry instead of overwriting it.
2. Run `npx -y @maxsbond/figma-bridge setup` to copy the Figma plugin to ~/Documents/Figma Bridge Plugin.
3. Tell me how to import the plugin in Figma Desktop (Plugins → Development → Import plugin from manifest…, pick manifest.json from that folder) and how to run it in my file (Plugins → Development → Figma Bridge).
4. Tell me if I need to restart you. After the restart, call figma_status to check the connection.

Prefer to do it by hand? Follow the steps below or the step-by-step guide.

Install

There are two parts: the MCP server, which your AI agent starts on its own, and the Figma plugin, which you import into Figma once. The server is published on npm as @maxsbond/figma-bridge, so there is nothing to clone or build.

New to this? The step-by-step guide walks through the same setup with screenshots and tells you what to say to your agent.

1. Add the server to your agent

VS Code (GitHub Copilot): click Install in VS Code and confirm in VS Code. Other agents are in the sections below.

2. Set up the Figma plugin

You import the plugin once. After that you only need to run it (step 4).

1. Get the plugin files. Run this in a terminal:

npx -y @maxsbond/figma-bridge setup

It copies the plugin to Documents/Figma Bridge Plugin and opens that folder. Run it again after updating to get the new plugin version.

2. Import the plugin. In Figma Desktop open any design file, click the Figma logo in the top-left corner and go to Plugins → Development → Import plugin from manifest… (right-clicking the canvas gets you the same Plugins menu).

Plugins → Development → Import plugin from manifest…

3. Pick manifest.json in the Figma Bridge Plugin folder and click Open. "Figma Bridge" now shows up under Plugins → Development.

Selecting manifest.json in the file dialog

4. Run the plugin whenever you want the agent to work in Figma: open the file and pick Plugins → Development → Figma Bridge.

Plugins → Development → Figma Bridge

5. Check the connection. The small plugin window says connected to MCP server once an agent with this MCP is running (see the next sections). If the agent isn't running yet, it says "disconnected — retrying…" and connects by itself when the agent starts. Keep the window open while you work, since closing it stops the bridge.

Figma Bridge plugin window: connected to MCP server

From source

If you'd rather run a checkout: clone the repo, run npm install, import plugin/manifest.json from it, and in the configs below use node with /absolute/path/to/figma-bridge/server.js instead of npx -y @maxsbond/figma-bridge.

Use with Claude

Claude Code

claude mcp add --scope user figma-bridge -- npx -y @maxsbond/figma-bridge

Check it with claude mcp list, or /mcp inside a session. Exports go to ./figma-exports/ in the directory you started claude from.

Or install it as a plugin, which adds the MCP server and the skill in one go. Inside a Claude Code session:

/plugin marketplace add MaxsBond/figma-bridge
/plugin install figma-bridge@figma-bridge

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "figma-bridge": {
      "command": "npx",
      "args": ["-y", "@maxsbond/figma-bridge"],
      "env": {
        "FIGMA_BRIDGE_OUT_DIR": "/absolute/path/to/figma-exports"
      }
    }
  }
}

Restart Claude Desktop. Set FIGMA_BRIDGE_OUT_DIR here because a desktop app doesn't start the server in a folder you'd want exports in.

Use with Codex

Works for the Codex CLI, the Codex IDE extension and the ChatGPT desktop app. They all read ~/.codex/config.toml.

codex mcp add figma-bridge -- npx -y @maxsbond/figma-bridge

or add it by hand:

[mcp_servers.figma-bridge]
command = "npx"
args = ["-y", "@maxsbond/figma-bridge"]
# Codex's default per-tool timeout is 60 s; big exports and scripts can take longer.
tool_timeout_sec = 180

# optional
# [mcp_servers.figma-bridge.env]
# FIGMA_BRIDGE_OUT_DIR = "/absolute/path/to/figma-exports"

Check it with codex mcp list, or /mcp inside the Codex TUI.

Use with GitHub Copilot

VS Code (Copilot Chat, agent mode)

The Install in VS Code link above adds the server to your user settings. To add it to one project instead, create .vscode/mcp.json:

{
  "servers": {
    "figma-bridge": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@maxsbond/figma-bridge"],
      "env": {
        "FIGMA_BRIDGE_OUT_DIR": "${workspaceFolder}/figma-exports"
      }
    }
  }
}

Click Start above the server entry (or run MCP: List Servers → figma-bridge → Start), switch Copilot Chat to Agent mode and make sure the figma_* tools are ticked in the tools picker. MCP tools aren't available in Ask/Edit mode. On Copilot Business/Enterprise your organization admin has to allow MCP servers.

Copilot CLI

Add it with /mcp add inside copilot, or edit ~/.copilot/mcp-config.json:

{
  "mcpServers": {
    "figma-bridge": {
      "type": "local",
      "command": "npx",
      "args": ["-y", "@maxsbond/figma-bridge"],
      "tools": ["*"]
    }
  }
}

Tools

Tool What it does
figma_status Connection check: file name/key, current page, selection
figma_list_pages Pages of the open file
figma_get_tree id / name / type / box outline to a given depth, for finding node ids
figma_export_json Node JSON to disk: rest (same shape as the REST API, JSON_REST_V1), compact (trimmed, with style/variable/component names resolved) or auto
figma_export_image PNG / JPG / SVG / PDF render to disk
figma_export_image_fills Original raster images used in image fills
figma_run_script Arbitrary Plugin API JavaScript (read and write), figma in scope, top-level await, use return

Node ids can be given as 1:2, 1-2 or a full Figma URL with ?node-id=. Results over ~15 KB are saved to a file and the tool returns the path instead.

Things to try once it's connected:

  • "What's selected in Figma? Export it as PNG and JSON."
  • "Build this React component from Figma node 12:345."
  • "Rename every layer called Frame 12… on this page to something meaningful."
  • "Make a dark variant of the selected component set."

Agent skill

skills/figma-bridge/ is a skill that tells the agent when to reach for the figma_* tools and how to use them well: check the connection first, find nodes cheaply, export instead of dumping JSON inline, write safe Plugin API scripts, and build code from a frame. It also walks the agent through setup when the server or plugin is missing.

  • Claude Code: the plugin install above includes it. Or copy the folder to ~/.claude/skills/figma-bridge/.
  • Other agents that support skills (Codex, Cursor, Copilot and others): copy the folder to wherever your agent loads skills from.
  • Zip for skill marketplaces: npm run pack:skill builds dist/figma-bridge-skill.zip with SKILL.md at the root.

Configuration

Env var Default Meaning
FIGMA_BRIDGE_OUT_DIR <cwd>/figma-exports Where exports are written (<dir>/<file name>/…)
FIGMA_BRIDGE_PORT 3055 WebSocket port. If you change it, change it in plugin/manifest.json (devAllowedDomains) and plugin/ui.html (PORT) too
FIGMA_BRIDGE_TIMEOUT_MS 120000 How long to wait for the plugin to answer one request

Troubleshooting

"Figma plugin is not connected": run Plugins → Development → Figma Bridge in the file you want to work on. The plugin only sees that one file.

"Port 3055 is already taken": only one server can hold the port, and the plugin talks to whoever does. This happens when two agents run at once (say Claude Code and Codex both have the MCP enabled) or an old server process is still alive. Find it with

lsof -iTCP:3055 -sTCP:LISTEN

and close that agent or kill the process. The next figma_* call retries the bind, and the plugin reconnects within ~10 s. To run two agents at the same time, give one of them a different FIGMA_BRIDGE_PORT and a second copy of the plugin pointing at that port.

Scripts fail with "Cannot unwrap symbol": the result contains figma.mixed (for example the fontSize of a text node with mixed sizes). Convert it before returning, e.g. JSON.parse(JSON.stringify(value, (k, v) => typeof v === 'symbol' ? 'MIXED' : v)).

Node not found / page not loaded in scripts: the plugin uses documentAccess: dynamic-page, so use the async APIs (figma.getNodeByIdAsync, node.getMainComponentAsync(), page.loadAsync() / figma.loadAllPagesAsync()). figma.currentPage is whatever page is open in Figma right now, so address nodes by id rather than relying on it.

Security

The WebSocket listens on 127.0.0.1 only and accepts connections only with Origin: null (the plugin's sandboxed iframe), so regular web pages can't talk to it. Keep in mind that figma_run_script runs whatever code the agent sends with full edit rights on the open file. Figma's undo works for it, but review what your agent is doing in files that matter.

License

MIT

About

Local MCP server + Figma dev plugin that lets Claude, Codex and GitHub Copilot read and edit the file open in Figma Desktop. Works on a View seat, no rate limits.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages