@addition/figma-pilot

MCP server that enables AI agents (Claude, Cursor, Codex, and any MCP-compatible client) to create and modify Figma designs through natural language.

English | 中文

Quick Start

1. Configure MCP

Claude Code:

claude mcp add figma-pilot -- npx @addition/figma-pilot

Claude Desktop:

Add to your MCP config file (usually ~/.config/claude/claude_desktop_config.json on macOS/Linux, or %APPDATA%\Claude\claude_desktop_config.json on Windows):

Cursor:

Add to your Cursor MCP config file (usually ~/.cursor/mcp.json or in Cursor settings):

Codex / Other MCP Clients:

Add to your MCP config file (location varies by client):

{
  "mcpServers": {
    "figma-pilot": {
      "command": "npx",
      "args": ["@addition/figma-pilot"]
    }
  }
}

2. Install the Figma Plugin

1. Download figma-pilot-plugin-vX.X.X.zip from GitHub Releases
2. Unzip the file
3. In Figma Desktop: Plugins → Development → Import plugin from manifest
4. Select the manifest.json file from the unzipped folder
5. Run the plugin in your Figma file (Plugins → Development → figma-pilot)

3. Start Using

Once the MCP is configured and the Figma plugin is running, you can ask your AI agent to:

• "Create a login form in Figma"
• "Add a navigation bar with logo and menu items"
• "Change the selected element's color to blue"
• "Check accessibility and fix any issues"

Available Tools

figma-pilot uses code execution mode for maximum efficiency:

| Tool | Description | |------|-------------| | figma_status | Check connection to Figma plugin | | figma_execute | Execute JavaScript with full Figma API access | | figma_get_api_docs | Get detailed API documentation |

Why Only 3 Tools?

Traditional MCP servers expose many tools, but each tool definition consumes context tokens. With code execution:

• 90%+ fewer tokens in tool definitions
• Batch operations in a single call
• Data filtering before returning results
• Complex logic with loops and conditionals

Example Usage

// figma_execute: Create a card with auto-layout
await figma.create({
  type: "card",
  name: "User Card",
  width: 320,
  layout: { direction: "column", gap: 16, padding: 24 },
  children: [
    { type: "text", content: "John Doe", fontSize: 18, fontWeight: 600 },
    { type: "text", content: "[email protected]", fontSize: 14, fill: "#666666" }
  ]
});

// figma_execute: Batch modify all selected rectangles
const { nodes } = await figma.query({ target: "selection" });
for (const node of nodes.filter(n => n.type === "RECTANGLE")) {
  await figma.modify({ target: node.id, fill: "#0066FF", cornerRadius: 8 });
}

// figma_execute: Check and fix accessibility
const result = await figma.accessibility({ target: "page", level: "AA", autoFix: true });
console.log(`Fixed ${result.fixedCount} issues`);

// figma_execute: Export for review
await figma.export({ target: "selection", format: "png", scale: 2 });

Available APIs

All operations are available on the figma object inside figma_execute:

• figma.status() - Check connection
• figma.query({ target }) - Query elements
• figma.create({ type, ... }) - Create elements
• figma.modify({ target, ... }) - Modify elements
• figma.delete({ target }) - Delete elements
• figma.append({ target, parent }) - Move into container
• figma.listComponents({ filter? }) - List components
• figma.instantiate({ component }) - Create instance
• figma.toComponent({ target }) - Convert to component
• figma.createVariants({ ... }) - Create variants
• figma.accessibility({ target }) - WCAG checking
• figma.createToken({ ... }) - Create design token
• figma.bindToken({ ... }) - Bind token
• figma.syncTokens({ ... }) - Import/export tokens
• figma.export({ target, format }) - Export image

Use figma_get_api_docs to get detailed parameter documentation.

How It Works

┌─────────────┐     stdio      ┌─────────────────┐     HTTP      ┌──────────────┐
│ MCP Client  │ ◄────────────► │  MCP Server     │ ◄───────────► │ Figma Plugin │
│(Claude/Cursor│                │  (with bridge)  │   port 38451  │              │
│  /Codex/etc)│                └─────────────────┘               └──────────────┘
└─────────────┘

The MCP server includes a built-in HTTP bridge that the Figma plugin connects to. No separate server process needed.

Environment Variables

All variables are optional. Copy .env.example from the project root to .env and uncomment the ones you want to change.

Debugging & Tracing

| Variable | Default | Description | |----------|---------|-------------| | FIGMA_PILOT_VERBOSE | false | Set to true or 1 to enable verbose trace logging to stderr. Logs every tool call, bridge operation (with params and elapsed ms), and execution outcome. When active, the plugin UI shows a SRV VERBOSE badge. |

Example — Claude Code:

{
  "mcpServers": {
    "figma-pilot": {
      "command": "npx",
      "args": ["@addition/figma-pilot"],
      "env": { "FIGMA_PILOT_VERBOSE": "true" }
    }
  }
}

Example — shell / dev:

FIGMA_PILOT_VERBOSE=true npx @addition/figma-pilot

Bridge Server — Network

| Variable | Default | Description | |----------|---------|-------------| | FIGMA_PILOT_PORT | 38451 | TCP port the embedded HTTP bridge listens on. Change if the port is already in use. | | FIGMA_PILOT_HOST | localhost | Interface the bridge binds to. Use 0.0.0.0 only if the plugin must connect from another host. |

Bridge Server — Timeouts & Limits

| Variable | Default | Description | |----------|---------|-------------| | FIGMA_PILOT_TIMEOUT_MS | 10000 | Milliseconds the server waits for the plugin to respond to one operation. Increase for slow operations such as exporting large pages. | | FIGMA_PILOT_HEALTH_TTL_MS | 15000 | Milliseconds after the last plugin poll before the bridge considers the plugin disconnected. | | FIGMA_PILOT_MAX_QUEUE | 100 | Maximum queued operations. Requests beyond this are rejected with HTTP 429. | | FIGMA_PILOT_MAX_PENDING | 100 | Maximum in-flight operations awaiting a response. Requests beyond this are rejected with HTTP 429. | | FIGMA_PILOT_MAX_BODY_BYTES | 10000000 | Maximum HTTP request body size in bytes (default 10 MB). The higher limit accommodates base64-encoded images. |

Requirements

• Node.js >= 18
• Figma Desktop app
• The figma-pilot Figma plugin running

License

MIT