mcp-figma

MCP server that bridges AI clients (Claude, Cursor, GPT) to Figma Desktop via Plugin API + WebSocket. Zero rate limits, free, real-time design manipulation.

Why This Exists

Figma's REST API is rate-limited (6 calls/month on free tier) and existing MCP servers all wrap that same API. mcp-figma takes a different approach — it uses the Figma Plugin API running inside your desktop app, which has no rate limits and is completely free.

How It Works


Open interactive architecture diagram on Excalidraw

Three components run simultaneously:

| Component | What it does | How to start | |-----------|-------------|--------------| | WebSocket Server | Relay with token auth + channel routing | npm run ws | | Figma Plugin | Executes commands inside Figma Desktop | Import in Figma | | MCP Server | Exposes 25 design tools to AI via stdio | Configure in AI client |

Quick Start

Prerequisites

• Node.js 18+ (download)
• Figma Desktop (download)

Step 1: Install & Build

git clone https://github.com/tranhoangtu-it/mcp-figma.git
cd mcp-figma
npm install
npm run build

Step 2: Start WebSocket Server

npm run ws

Output: `` [ws] WebSocket server listening on 127.0.0.1:3055 [ws] Session token: abc123... ← Copy this token! ``

Step 3: Import Figma Plugin

1. Open Figma Desktop
2. Go to Plugins → Development → Import plugin from manifest...
3. Navigate to mcp-figma/src/figma-plugin/ and select manifest.json
4. Run the plugin: Plugins → Development → MCP Figma Bridge
5. Paste the session token from Step 2 → Click Connect
6. Status dot turns green = connected

Step 4: Configure Your AI Client

Claude Code

Add to your project's .mcp.json: ``json { "mcpServers": { "mcp-figma": { "command": "node", "args": ["/absolute/path/to/mcp-figma/dist/mcp-server/index.js"], "env": { "MCP_FIGMA_TOKEN": "paste-token-from-step-2" } } } } ``

Cursor

Add to MCP settings (Settings → MCP Servers): ``json { "mcp-figma": { "command": "node", "args": ["/absolute/path/to/mcp-figma/dist/mcp-server/index.js"], "env": { "MCP_FIGMA_TOKEN": "paste-token-from-step-2" } } } ``

Windsurf / Other MCP Clients

Any MCP-compatible client works — configure it to run node dist/mcp-server/index.js with the MCP_FIGMA_TOKEN environment variable.

Step 5: Try It!

Ask your AI: "Create a login page in Figma with email input, password input, and a blue submit button"

Watch it appear in real-time on your Figma canvas.

Available Tools (25)

Read Design

| Tool | Description | |------|-------------| | get_document_info | Document name, pages, current page | | get_selection | Currently selected nodes | | get_node_info | Detailed properties of a node by ID | | get_page_nodes | All top-level nodes on a page | | scan_text_nodes | Find all text nodes in subtree | | scan_nodes_by_type | Find nodes by type (FRAME, TEXT, etc.) |

Create Nodes

| Tool | Description | |------|-------------| | create_frame | Frame with position, size, fill, auto-layout | | create_rectangle | Rectangle with fill and corner radius | | create_text | Text node (Inter font default) | | create_ellipse | Ellipse or circle |

Modify Nodes

| Tool | Description | |------|-------------| | move_node | Move to new X/Y coordinates | | resize_node | Change width and height | | set_name | Rename a node | | set_corner_radius | Round corners | | delete_node | Remove from canvas | | clone_node | Duplicate a node | | group_nodes | Group multiple nodes | | set_auto_layout | Configure auto-layout direction, spacing, padding |

Style Nodes

| Tool | Description | |------|-------------| | set_fill_color | Solid fill color (RGBA 0-1) | | set_stroke | Stroke color and width | | set_text_content | Update text content | | set_font_size | Change font size | | set_opacity | Set transparency (0-1) | | get_local_styles | List all local paint/text styles |

Export

| Tool | Description | |------|-------------| | export_node | Export as PNG, SVG, or PDF (base64) |

Configuration

| Environment Variable | Default | Description | |---------------------|---------|-------------| | MCP_FIGMA_TOKEN | (required) | Session token from WebSocket server | | MCP_FIGMA_PORT | 3055 | WebSocket server port | | MCP_FIGMA_CHANNEL | mcp-figma | Channel name for communication |

Development

npm run build     # Build with tsup
npm run dev       # Watch mode (auto-rebuild)
npm run ws        # Start WebSocket relay server
npm run start     # Start MCP server (needs MCP_FIGMA_TOKEN)
npm test          # Run all tests
npm run test:ws   # Run WebSocket tests only

Security

| Measure | Details | |---------|---------| | Localhost only | WebSocket binds to 127.0.0.1 — no remote access | | Token auth | Per-session random token, timing-safe comparison | | Channel isolation | Clients can only message their own channel | | Schema validation | All messages validated with Zod before processing | | Input sanitization | Design data sanitized before reaching AI | | Rate limiting | 100 messages/sec per client | | Heartbeat | Dead connections detected and cleaned up |

Troubleshooting

| Problem | Solution | |---------|----------| | Plugin won't connect | Check token matches, WS server is running, port 3055 not blocked | | "Font not found" error | Figma defaults to Inter — ensure it's installed or specify available font | | MCP server exits immediately | Check MCP_FIGMA_TOKEN is set and WS server is running | | Tools timeout after 30s | Ensure Figma plugin is connected (green status dot) | | Port 3055 in use | Set MCP_FIGMA_PORT=3056 for both WS server and MCP client config |

Contributing

See CONTRIBUTING.md for development setup, conventions, and how to add new tools.

License

MIT