Figma Bridge
by tanlugi
README.md
# Figma Bridge
An MCP server and a Figma plugin that let AI agents (Claude Code, Codex, or any MCP client) read and edit the Figma file open in **your own Figma app**, through the Plugin API.
Figma's hosted MCP server counts the read calls an account makes per day and per minute (see [its rate limits](https://developers.figma.com/docs/figma-mcp-server/rate-limits-access/)). Several agents working on one file reach that quickly. Figma Bridge takes another road: a plugin running inside your Figma, on your computer, talking to a local server. There is no count of calls.
Português: [README.pt-BR.md](README.pt-BR.md)
> Unofficial. Not affiliated with or endorsed by Figma. It only acts on files you have open, as you, with what any Figma plugin can do.
## How it works
- **`plugin/`** is the Figma plugin. It is the only part that touches the document.
- **`server/bridge.mjs`** is the MCP server the agents start. It talks to the plugin on this computer only (`127.0.0.1`, port 47821). No dependencies: Node 20 or newer is all it needs.
```
agent --MCP--> bridge.mjs --127.0.0.1--> (the first bridge that opened) <--asks for commands-- plugin in Figma
```
Every agent starts its own `bridge.mjs`. The first one takes the port and is the one the plugin talks to; the others send their calls through it, and one of them takes its place when it leaves. Commands wait in a queue and run one at a time.
## Install (once)
1. **Import the plugin.** In the Figma desktop app, open any file and go to `Plugins › Development › Import plugin from manifest…`. Pick `plugin/manifest.json` of this folder.
2. **Open it.** `Plugins › Development › Figma Bridge`. A small window says the key is missing.
3. **Copy the key.** In a terminal, in this folder:
```
node server/bridge.mjs --pair
```
The key goes to the clipboard (it is not printed). Paste it in the plugin's window and save. Figma keeps it on this computer; you do this once. On systems without a clipboard command, the answer says which file holds the key.
4. **Connect your agents.** See below.
## Connect your agents
The server is always the same command: `node` with the path of `server/bridge.mjs`.
**Any MCP client that reads `.mcp.json`** (Claude Code in a project, for example):
```json
{
"mcpServers": {
"figma-bridge": {
"command": "node",
"args": ["/path/to/figma-bridge/server/bridge.mjs"]
}
}
}
```
**Claude Code, for every project:**
```
claude mcp add figma-bridge --scope user -- node "/path/to/figma-bridge/server/bridge.mjs"
```
**Codex**, in `~/.codex/config.toml`:
```toml
[mcp_servers.figma-bridge]
command = "node"
args = ["/path/to/figma-bridge/server/bridge.mjs"]
```
## Day to day
- Open the file in Figma and run `Plugins › Development › Figma Bridge`. **Its window must stay open** while the agents work.
- The dot turns green when an agent with Figma Bridge is running. With none, it says it is looking for the server and connects by itself later.
- From a terminal: `node server/bridge.mjs --status`.
- What the agents change shows in the file at once and is yours to undo with Ctrl+Z, one step per command.
## Tools
| Tool | What it does |
| --- | --- |
| `figma_status` | Whether the plugin is running, in which file, its pages and the selection. |
| `figma_tree` | The layers under a node as a list: id, type, name, position, size, auto layout, clipping, text, color. |
| `figma_find` | Finds nodes by name and type, on the current page, one page or all of them. |
| `figma_screenshot` | Pictures of up to 12 nodes in one call. With `saveTo`, also writes them as files (PNG, JPG or SVG), named after the node and its id. |
| `figma_audit` | Measures a frame and lists layout problems, with ids and pixels (see below). |
| `figma_run` | Runs JavaScript with the Figma Plugin API: reads and edits anything. `shot(node)` returns a picture, `log()` returns lines. |
| `figma_place_image` | Brings a picture from this computer (PNG, JPG or GIF) into the file: as a new layer, or as the fill of a node that is already there. |
| `figma_show` | Selects nodes and brings your Figma window to them. |
### What `figma_audit` reports
- Texts drawn over each other (a copy of the same words right behind, used as an outline, does not count).
- Controls of the same group that overlap without one being inside the other, such as tabs over a header.
- Content cut by a frame that clips, hidden by it, or outside the audited frame.
- Text larger than its own box, and a short label that wrapped into more than one line (a price, a button's text).
- Placeholder words where an icon should be ("icon", "eye", "gift"…) and dashed boxes with no art in them.
- Text smaller than 10 px (`minFont` changes it).
Not reported, because that is how such screens are drawn: outlines of two texts that touch by 1 or 2 px, rows scrolled out of a list, a window's frame under its header and close button, and lists made to scroll.
It does not judge style, spacing or colors, and it does not see an empty spot with nothing marking it: looking at the picture is still part of the job.
## Limits
- It needs Figma open on this computer, in the right file, with the plugin's window open. Without it, the agents get a message asking the person to open it.
- One plugin runs per file: opening another plugin closes Figma Bridge.
- With the plugin open in more than one file, the agent picks one by name (the `file` argument); with no name, the last one opened gets the call.
- One command at a time per file. Several agents can use it together; their calls wait in the queue.
- The current page and the selection are yours and one for every agent: agents should name nodes and pages by id.
- It does not do what only Figma's hosted MCP does: searching team libraries, Code Connect, comments, FigJam and Slides.
## Security
- The server listens on this computer only (`127.0.0.1` and `::1`), never on the network.
- Everything needs the key, kept in `%LOCALAPPDATA%\FigmaBridge\key` on Windows or `~/.figma-bridge/key` elsewhere, and made on the first run. Without it, a web page open in a browser cannot send commands to your Figma.
- The key never goes into a project, a log or the agents' conversation. To change it: delete the file, run `--pair` again and use "Change the key" in the plugin's window.
- `figma_run` runs the code the agent writes, with the reach of a plugin: the open file. It has no disk and no network.
- The server only writes pictures (`saveTo`) inside the folder the agent works in. To allow other folders, list them in `FIGMA_BRIDGE_WRITE_DIRS` for whoever starts the server (separated by `;` on Windows, `:` elsewhere). From disk it only reads picture files, and only the ones an agent names in `figma_place_image`.
## Changing the port
Port 47821 is in three places that must match: the `FIGMA_BRIDGE_PORT` variable of whoever starts the server, `devAllowedDomains` in `plugin/manifest.json`, and `BASE` in `plugin/ui.html`.
## Tests
```
node --test
```
They cover the server (MCP, the key, the queue, two agents sharing the port, several files, timeouts, writing and reading pictures) and the plugin's commands over a stand-in document (the audit, the tree, find, the script, placing pictures).
## License
[MIT](LICENSE)
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessOutdated data