Agent to Figma MCP

A TypeScript monorepo that enables AI agents (like Claude) to interact with Figma designs through the Model Context Protocol (MCP).

Architecture

┌─────────────────┐     stdio        ┌─────────────────┐     WebSocket      ┌─────────────────┐
│   Claude Code   │◄────────────────►│   MCP Server    │◄──────────────────►│  Relay Server   │
│   (MCP Client)  │                  │  (port: stdio)  │                    │  (port: 3055)   │
└─────────────────┘                  └─────────────────┘                    └────────┬────────┘
                                                                                     │
                                                                                     │ WebSocket
                                                                                     ▼
                                                                            ┌─────────────────┐
                                                                            │  Figma Plugin   │
                                                                            │  (in Figma)     │
                                                                            └─────────────────┘

Packages

Package	Description
apps/mcp-server	MCP server with 50+ tools for Figma manipulation
apps/relay-server	WebSocket relay for Figma plugin communication
apps/figma-plugin	Figma plugin that executes commands
packages/types	Shared TypeScript types

Quick Start

Prerequisites

• Bun v1.0+
• Figma Desktop App

Installation

# Clone the repository
git clone https://github.com/anthropics/agent-to-figma-mcp.git
cd agent-to-figma-mcp

# Install dependencies
bun install

# Build all packages
bun run build

Running

1. Start the Relay Server

bun run --filter=@caelinsutch/relay-server start

The relay server runs on ws://localhost:3055.

2. Install the Figma Plugin

1. Open Figma Desktop
2. Go to Plugins → Development → Import plugin from manifest...
3. Select apps/figma-plugin/manifest.json
4. Run the plugin from Plugins → Development → Figma MCP Plugin

3. Configure Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "agent-to-figma": {
      "command": "node",
      "args": ["/path/to/agent-to-figma-mcp/apps/mcp-server/dist/index.js"],
      "env": {
        "RELAY_URL": "ws://localhost:3055",
        "CHANNEL_NAME": "figma"
      }
    }
  }
}

4. Connect

1. In the Figma plugin UI, enter the channel name (default: figma)
2. Click Connect
3. Start chatting with Claude about your Figma designs!

Available Tools

Document & Selection

• get_document_info - Get current document information
• get_selection - Get currently selected nodes
• get_node_info - Get detailed info about a node
• read_my_design - Read selected design nodes

Shape Creation

• create_rectangle - Create a rectangle
• create_frame - Create a frame with auto-layout support
• create_text - Create text nodes

Styling

• set_fill_color - Set fill color
• set_stroke_color - Set stroke color
• set_corner_radius - Set corner radius

Transform

• move_node - Move a node
• resize_node - Resize a node
• delete_node - Delete a node
• clone_node - Clone a node

Layout

• set_layout_mode - Set auto-layout mode
• set_padding - Set padding
• set_axis_align - Set axis alignment
• set_item_spacing - Set item spacing

Components

• get_local_components - List local components
• create_component_instance - Create component instance
• get_instance_overrides - Get instance overrides
• set_instance_overrides - Apply overrides to instances

Variables (NEW)

• get_local_variable_collections - List variable collections
• create_variable_collection - Create a collection
• create_variable - Create a variable
• set_variable_value_for_mode - Set variable value
• bind_variable_to_node - Bind variable to node property
• unbind_variable_from_node - Remove variable binding
• And more...

Export & Prototyping

• export_node_as_image - Export node as PNG/JPG/SVG/PDF
• get_reactions - Get prototype reactions
• create_connections - Create prototype connections

Development

Build

# Build all packages
bun run build

# Build specific package
bun run build --filter=@caelinsutch/mcp-server

Type Check

# Type check all packages
bun run type:check

# Type check specific package
bun run type:check --filter=@caelinsutch/mcp-server

Development Mode

# Run relay server in dev mode
bun run --filter=@caelinsutch/relay-server dev

# Run Figma plugin in dev mode
bun run --filter=@caelinsutch/figma-plugin dev

Project Structure

agent-to-figma-mcp/
├── apps/
│   ├── mcp-server/           # MCP server (stdio transport)
│   │   ├── src/
│   │   │   ├── tools/        # Feature-based tool modules
│   │   │   │   ├── document.ts
│   │   │   │   ├── nodes.ts
│   │   │   │   ├── shapes.ts
│   │   │   │   ├── text.ts
│   │   │   │   ├── styling.ts
│   │   │   │   ├── transform.ts
│   │   │   │   ├── layout.ts
│   │   │   │   ├── components.ts
│   │   │   │   ├── variables.ts
│   │   │   │   └── ...
│   │   │   ├── prompts/      # MCP prompts
│   │   │   ├── communication/ # WebSocket client
│   │   │   └── index.ts
│   │   └── package.json
│   │
│   ├── relay-server/         # WebSocket relay
│   │   ├── src/
│   │   │   ├── server.ts     # Bun WebSocket server
│   │   │   ├── channels.ts   # Channel management
│   │   │   └── index.ts
│   │   └── package.json
│   │
│   └── figma-plugin/         # Figma plugin
│       ├── src/
│       │   ├── plugin/
│       │   │   ├── handlers/ # Command handlers
│       │   │   ├── utils/    # Utilities
│       │   │   └── code.ts   # Main entry
│       │   └── ui/           # Plugin UI
│       └── manifest.json
│
├── packages/
│   └── types/                # Shared TypeScript types
│       └── src/
│           ├── commands.ts
│           ├── figma/
│           │   ├── nodes.ts
│           │   ├── variables.ts
│           │   └── ...
│           └── communication/
│
└── turbo.json

Environment Variables

MCP Server

Variable	Default	Description
RELAY_URL	ws://localhost:3055	WebSocket relay URL
CHANNEL_NAME	figma	Channel to join

Relay Server

Variable	Default	Description
PORT	3055	Server port

Troubleshooting

Plugin not connecting

1. Ensure the relay server is running
2. Check that the channel name matches in both plugin and MCP server
3. Verify Figma has network access permissions

Commands timing out

1. Check Figma plugin is connected (green indicator)
2. Ensure the node IDs are valid
3. Try reconnecting the plugin

Type errors during build

# Clean and rebuild
bun run clean
bun install
bun run build

License

MIT