What is the Relai MCP server?
Relai is an MCP server in syoooo/figma-relai that connects an AI coding agent to Figma through a desktop plugin. The agent reads, edits, audits and builds design systems with 33 tools, and the Figma file itself carries conventions, precedents and no-go zones.
Relai connects Claude Code, Cursor, Codex or any MCP client to Figma, so the agent can read, edit, audit and build design systems. Writes go through the Relai Figma plugin, which is why it works on every Figma plan.
The architecture is an AI client talking over stdio to the MCP server, which hosts a WebSocket relay on 127.0.0.1:9055. The Figma plugin connects to that relay and executes the Plugin API calls.
The file carries the rules
Conventions, precedents and no-go pages live inside the Figma file as plugin data. Any client that connects through Relai inherits them, and an edit that breaks a rule is refused before it runs.
Conventions cover naming rules, token routing and spacing habits that the AI reads before working. Memory records rulings such as a gap that is on purpose, and attaches them to any later edit that touches what they reference.
Audits and design systems
The analyze_design tool checks color token coverage, auto layout quality, component health and accessibility, or all four at once as a weighted 0 to 100 health score. Deviations you already ruled intentional stay waived.
For design systems it covers variable collections with modes, token binding, shared styles, components with variants and team library imports. get_design_system inventories what the file and its libraries already have.
Control for the designer
The plugin shows a live activity feed of every command with timing, an indicator that an agent is paired, and a Stop button that cancels the rest of a batch. Lock to selection rejects edits outside what you selected.
Who the Relai MCP server is for
Best for
- Designers who want bulk edits, such as recoloring a screen for dark mode, as one round trip across many layers.
- Teams that want conventions, precedents and fenced pages stored in the Figma file so every client inherits them.
- Auditing a file for color token coverage, auto layout, components and WCAG contrast with a health score.
Not for
- Agents connected through a different Figma bridge, because the file's rules only bind clients that connect through Relai.
- Comment threads or a library's full component catalog without a Figma personal access token.
Connect Relai MCP Server: Edit and Audit Figma with an AI Coding Agent to your AI client
claude mcp add Relai -- npx -y figma-relaiInstall the plugin
Download relai-plugin-<version>.zip from the latest release, unzip it, then open Plugins, Development, Import plugin from manifest in Figma Desktop and pick manifest.json. Keep the panel open in the file you want to edit.
Register the server
Run the command above for Claude Code, or
codex mcp add Relai -- npx -y figma-relaifor Codex CLI. For Cursor, put the config above in.cursor/mcp.json.Ask for something
Pairing is automatic and nothing is copied between windows. A good first ask is: How is this screen put together?
Troubleshoot
Run
npx figma-relai doctorto check Node, the relay ports, plugin presence, the saved room and the Figma token.
Client configuration
{ "mcpServers": { "Relai": { "command": "npx", "args": ["-y", "figma-relai"] } } }Endpoints and ports
127.0.0.1:9055WebSocket room hub embedded in the MCP server. The plugin manifest allowlists ws://localhost:9055 to 9057.https://github.com/syoooo/figma-relai/releases/latestDownload the plugin zip and import its manifest.json in Figma Desktop.npx figma-relai doctorChecks Node, relay ports, plugin presence, the saved room and the Figma token, each with its fix.What you can do with it
- Works on every planWrites go through the Relai Figma plugin rather than the paid REST API, so it works on every Figma plan, free included.
- Design auditsanalyze_design checks color token coverage, auto layout, components and accessibility, or returns all four as a weighted 0 to 100 health score.
- Design system toolsVariable collections with modes, token binding, shared styles, components with variants and team library imports run as declarative operations.
- Conventions and memoryNaming rules, token routing and recorded precedents are stored in the file, and every client that opens it inherits them.
- No-go zonesWrites into a guarded page are rejected before they run, with the reason on the receipt, and only you edit the guard list.
- Confirmation dialA dial with four stops, OPEN, RISK, BULK and ALL. At RISK, the default, only destructive operations ask, and agents cannot move the dial.
- Lock to selectionEdits outside the current selection are rejected, and the AI gets a clear error instead of a silent pass.
- Code execution toggleexecute_figma runs JavaScript against the Figma Plugin API, and the plugin's Allow code execution toggle turns it off.
Tools it exposes
get_document_overview, get_selection_context, get_design_tokens
Context group tools, listed with get_node_details, search_nodes, screenshot and get_events.
screenshot
Lets the AI look at the canvas rather than guess.
analyze_design
Checks color, layout, components, accessibility or overall, and returns a weighted 0 to 100 health score for all four.
diff_nodes
Compares nodes, or saves and compares checkpoints, to show exactly what changed.
verify_changes, verify_visual
Verification group tools, listed with validate_design_rules.
get_node_data
Reads a node as summary, tree, full, css or variables.
set_properties
Edit tool that sets properties on many nodes in one call.
create_node
Creates nodes on the canvas.
get_design_system
Inventories what the file and the libraries it uses already have, including components not yet placed in the file when a token is set.
manage_variables
Manages variable collections in the design system.
manage_comments
Reads comment threads and replies. Needs a Figma token.
execute_figma
Runs JavaScript against the Figma Plugin API through a relai helper library.
join_room
Selects which plugin to control when two Figma files run the plugin at the same time.
Frequently asked questions
What is the Relai MCP server?
Relai is an MCP server in syoooo/figma-relai that connects an AI coding agent to Figma through a desktop plugin. The agent reads, edits, audits and builds design systems with 33 tools, while the file itself carries the conventions, precedents and no-go zones that every client inherits.
How do I connect Relai to my AI coding agent?
Import the plugin from the latest release zip in Figma Desktop, then register the server. In Claude Code run claude mcp add Relai -- npx -y figma-relai. For Codex use codex mcp add with the same arguments, and for Cursor add the Relai entry with npx and the -y flag to .cursor/mcp.json.
What do I need before I start?
You need Figma Desktop, Node.js 18 or newer and an MCP client. The plugin must be open in the file you want to edit, because writes go through its panel. Pairing is automatic after that, and the first npx run is slow only because it downloads the package once.
Does Relai work on a free Figma plan?
Yes. Writes go through the Relai Figma plugin rather than the paid REST API, so it works on every plan, free included. Figma's own official MCP server and Design Agent are reserved for full seats on paid plans, and Relai can run alongside them.
Does my design data leave my machine?
The relay is local. It binds to 127.0.0.1 only, and file contents move only between Figma, your machine and the AI client you already trust. The relay has no authentication beyond room names, which carry a crypto random suffix. A Figma token, if you set one, is sent only to api.figma.com.
Can I undo a bad edit?
There is no magic undo. The activity feed is your reconstruction and diff_nodes checkpoints tell you exactly what changed, while Figma's version history is the restore path. A Stop button also cancels the rest of a pending batch before it finishes.
When do I need a Figma token?
Only for comments and a library's full component catalog, which sit behind Figma's REST API. Run npx figma-relai login to store a personal access token from a hidden prompt, and npx figma-relai logout to remove it. Every other tool works without it.
What does the confirmation dial control?
It sets when the plugin asks before acting, with four stops: OPEN, RISK, BULK and ALL. At RISK, the default, only destructive operations ask, such as deleting variables or styles, detach and flatten. You set it in the panel, and agents cannot move it.