# 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](https://bun.sh/) v1.0+
- [Figma Desktop App](https://www.figma.com/downloads/)

### Installation

```bash
# 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

```bash
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):

```json
{
  "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

```bash
# Build all packages
bun run build

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

### Type Check

```bash
# Type check all packages
bun run type:check

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

### Development Mode

```bash
# 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

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

## License

MIT