Figma 设计读写 MCP 服务

figma-pilot-mcp

Read and edit Figma designs through MCP and a local plugin.

Figma Pilot connects your AI agent to the open document in Figma Desktop through a local WebSocket relay.

Agent: "Read the Card component and build a matching Modal."
  → pilot_get_selection      inspect what's selected
  → pilot_create_node_tree   build the new frame in one call
  → pilot_set_auto_layout    match the spacing

Five design stages exported during a live MCP session in Figma Desktop: create a canvas, chain commands, add text, apply auto layout, and refine colors and copy.

Features

• Full read-write access — 97 tools covering nodes, styles, variables, components, prototypes, and export
• Bidirectional — read a design to generate code, or generate a design from a prompt
• Batch operations — chain commands with result references ($0.id) in one round trip
• Flexible deployment — all-in-one, or split MCP and WebSocket for multi-agent setups

How It Works

The MCP server uses stdio to talk to your agent and WebSocket to reach the plugin's UI iframe. The plugin main thread reads and edits the document:

graph LR
  A[AI Agent] <--stdio--> B[MCP Server]
  B <--ws--> C[Figma Plugin]
  C <--> D[Figma Document]

The plugin joins a channel shown in its UI; the MCP server connects to that same channel. The name uses the file key when available, otherwise the document name. Copy the displayed value to avoid connecting to a different document.

Prerequisites

• Bun 1.0+ — the server uses Bun.serve; development is verified with the version in packageManager.
• Figma Desktop — import and run the development plugin here.

Getting Started

Clone or download this repository, then run commands from its root.

1. Install dependencies and build the plugin:

   复制

   bun install
   bun run build
   

2. Import the plugin into Figma Desktop:

   • Plugins → Development → Import plugin from manifest...
   • Select the dist/plugin/manifest.json in this project folder

3. Configure your AI agent (see below)

4. Run the plugin and connect:

   • Open a design file in Design mode, run Plugins → Development → Figma Pilot
   • The plugin UI shows a channel name (e.g., figma-pilot-abc123)
   • In your AI agent, use pilot_connect with the channel name

Verify the setup at any time with bunx --package figma-pilot-mcp figma-pilot doctor.

Usage

Once connected, drive it in plain language — the agent picks the tools. A few things it handles well:

Design to code — read what exists, then generate from it:

"Read the selected frame and write a React component that matches it."

Code to design — build new UI from a description:

"Create a 320×180 card with a title, divider, and body text, using auto layout with 12px spacing."

Bulk edits — most modification tools accept an array of node IDs:

"Find every frame named Button/* and set its corner radius to 8."

Chaining commands

pilot_batch runs commands in sequence and lets later steps reference earlier results with $N:

{
  "commands": [
    {
      "command": "create_frame",
      "params": { "name": "Card", "width": 300, "height": 200 },
    },
    {
      "command": "create_text",
      "params": { "parentId": "$0.id", "characters": "Title" },
    },
    {
      "command": "set_auto_layout",
      "params": { "nodeId": "$0.id", "mode": "VERTICAL" },
    },
  ],
}

$0.id resolves to the id field of the first command's result. Dot paths may also index arrays: $0.children.0.id.

A reference must be the entire value. "prefix-$0.id" is left as a literal string, and "$0.id-suffix" is an error — the trailing text is read as part of the property name.

The batch stops on the first error by default. Set stopOnError: false to continue with later commands; failed entries occupy a null slot in results, so references keep their original indexes. Any failure sets isError: true and appears in errors, including reference resolution failures. executed counts processed entries, including failures.

Trimming responses

Read tools accept a fields array to cut response size — useful when a node has more properties than you need:

{ "nodeId": "1:23", "fields": ["id", "name", "width", "height"] }

Configure Your AI Agent

Mode 1: All-in-one (recommended)

graph LR
  A[AI Agent] <--stdio--> B[MCP + WS Server] <--ws--> C[Figma Plugin]

{
  "mcpServers": {
    "figma-pilot": {
      "command": "bunx",
      "args": ["--package", "figma-pilot-mcp", "figma-pilot", "start"],
    },
  },
}

Mode 2: Separate WS + MCP (multi-agent)

graph LR
  A[AI Agent A] <--stdio--> C[MCP only]
  B[AI Agent B] <--stdio--> D[MCP only]
  C <--ws--> E[WS Server]
  D <--ws--> E
  E <--ws--> F[Figma Plugin]

1. Start the WebSocket server:

   复制

   bunx --package figma-pilot-mcp figma-pilot start --mode=ws
   

2. Configure AI agents:

   复制

   {
     "mcpServers": {
       "figma-pilot": {
         "command": "bunx",
         "args": [
           "--package",
           "figma-pilot-mcp",
           "figma-pilot",
           "start",
           "--mode=mcp",
         ],
       },
     },
   }
   

Reference

Mode Summary

CLI Commands

Configuration

Troubleshooting

Start with bunx --package figma-pilot-mcp figma-pilot doctor — it checks the runtime, the plugin build, and port availability.

Available Tools

Connection

Creation

Text

Modification

Layout

Node Hierarchy

Instance Operations

Styles

Variables & Properties

Team Library

Export & Prototype

Reading

Events & Utilities

Batch

Development

bun install --frozen-lockfile
bun run check
bun run build

check runs TypeScript checks for the server and plugin, Biome, and tests. The TypeScript dependency uses npm:@typescript/typescript6@^6.0.2, and checks invoke tsc6 to stay on TypeScript 6. The build uses the installed esbuild dependency and writes dist/plugin; reload the development plugin after rebuilding.

Use bun run dev for the server, or bun run dev:ws and bun run dev:mcp for separate relay and MCP processes. The plugin implementation notes describe the message flow, API helpers, and how to add a tool. The manifest currently enables the Figma editor; FigJam commands require an appropriate editor configuration.

License

MIT