# 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
