npm package: @figmcp/mcp-server
Description: MCP Server for Figma - Connect Claude to Figma via Model Context Protocol
Latest version: 1.3.1

# @figmcp/mcp-server

MCP (Model Context Protocol) Server for Figma - Connect Claude to Figma for AI-powered design workflows.

## Installation

```bash
npm install @figmcp/mcp-server
```

Or use directly with npx:

```bash
npx @figmcp/mcp-server
```

## Quick Start

### 1. Start the WebSocket Relay Server

```bash
# Using Docker (recommended)
docker run -d -p 3055:3055 -p 3056:3056 vanitax/figmcp-relay

# With authentication enabled
docker run -d -p 3055:3055 -p 3056:3056 \
  -e AUTH_REQUIRED=true \
  -e OP_SERVICE_ACCOUNT_TOKEN=your-token \
  -e OP_API_KEYS_VAULT_REF=op://vault/item \
  vanitax/figmcp-relay
```

Or with docker-compose:

```yaml
services:
  figmcp-relay:
    image: vanitax/figmcp-relay
    ports:
      - "3055:3055"
      - "3056:3056"
    environment:
      - AUTH_REQUIRED=true
      - OP_SERVICE_ACCOUNT_TOKEN=${OP_SERVICE_ACCOUNT_TOKEN}
      - OP_API_KEYS_VAULT_REF=${OP_API_KEYS_VAULT_REF}
```

### 2. Install the Figma Plugin

1. In Figma: Plugins → Development → Import plugin from manifest
2. Select the `manifest.json` file from the plugin package

### 3. Configure Claude Code

Add to your MCP configuration (`.mcp.json` or `~/.claude/mcp_servers.json`):

```json
{
  "mcpServers": {
    "figmcp": {
      "command": "npx",
      "args": ["@figmcp/mcp-server"],
      "env": {
        "FIGMCP_API_KEY": "your-api-key"
      }
    }
  }
}
```

### 4. Connect

1. Open Figma and run the FigMCP plugin
2. Enter your API key in the plugin's Advanced settings
3. Click Connect
4. In Claude Code, the Figma tools will be available

## Environment Variables

### MCP Server

| Variable | Default | Description |
|----------|---------|-------------|
| `FIGMCP_API_KEY` | - | API key for authentication |
| `FIGMCP_WS_URL` | `ws://localhost:3055` | WebSocket relay server URL |
| `FIGMCP_HTTP_URL` | `http://localhost:3056` | HTTP API URL |

### Relay Server

| Variable | Default | Description |
|----------|---------|-------------|
| `AUTH_REQUIRED` | `false` | Enable authentication |
| `OP_SERVICE_ACCOUNT_TOKEN` | - | 1Password service account token |
| `OP_API_KEYS_VAULT_REF` | - | 1Password vault reference (op://vault/item) |
| `TOKEN_REFRESH_INTERVAL` | `300000` | Token refresh interval (ms) |
| `RATE_LIMIT_MAX` | `50` | WebSocket rate limit (msg/sec) |
| `HTTP_RATE_LIMIT_MAX` | `100` | HTTP rate limit (req/min) |

## Available Tools

### Connection
- `list_figma_channels` - List available Figma plugin channels
- `connect_to_figma` - Connect to a Figma plugin
- `get_connection_status` - Check connection status

### Document
- `get_document_info` - Get document information
- `get_current_page` - Get current page info
- `get_selection` - Get selected nodes
- `get_node_info` - Get node details
- `focus_node` - Focus viewport on a node

### Creation
- `create_frame` - Create a frame
- `create_rectangle` - Create a rectangle
- `create_ellipse` - Create an ellipse/circle
- `create_line` - Create a line
- `create_vector` - Create a vector path (SVG)
- `create_polygon` - Create a polygon
- `create_star` - Create a star
- `create_text` - Create text
- `create_component` - Create a component
- `create_instance` - Create component instance
- `group_nodes` - Group nodes

### Styling
- `set_fill_color` - Set fill color
- `set_stroke` - Set stroke
- `set_corner_radius` - Set corner radius
- `set_opacity` - Set opacity
- `set_visible` - Set visibility
- `set_rotation` - Set rotation
- `set_effects` - Set effects (shadow, blur)

### Layout
- `move_node` - Move a node
- `resize_node` - Resize a node
- `set_auto_layout` - Set auto layout

### Manipulation
- `delete_node` - Delete a node
- `clone_node` - Clone a node
- `rename_node` - Rename a node
- `set_text_content` - Set text content
- `flatten_node` - Flatten to vector
- `export_node` - Export as image

### Batch Operations (Performance)
- `batch_create` - Create multiple nodes in one call (up to 50)
- `batch_edit` - Edit multiple nodes in one call (up to 50)

**Batch Create Example:**
```json
{
  "operations": [
    { "type": "frame", "params": { "name": "Card", "width": 300, "height": 200 } },
    { "type": "rectangle", "params": { "name": "BG", "fillColor": "#FFFFFF" } },
    { "type": "text", "params": { "content": "Hello", "fontSize": 16 } }
  ]
}
```

**Batch Edit Example:**
```json
{
  "operations": [
    { "nodeId": "1:2", "action": "move", "params": { "x": 100, "y": 50 } },
    { "nodeId": "1:3", "action": "setFillColor", "params": { "color": "#FF0000" } },
    { "nodeId": "1:4", "action": "resize", "params": { "width": 200, "height": 100 } }
  ]
}
```

## Architecture

```
Claude Code ──MCP──> MCP Server ──WebSocket──> Relay Server ──WebSocket──> Figma Plugin
                         │                         │
                         └── FIGMCP_API_KEY        └── 1Password tokens
```

## Security Features

- **HMAC Signature Auth**: WebSocket connections authenticated via SHA256 signatures
- **Command Signing**: Write operations (create/delete) require signed commands
- **Rate Limiting**: Both WebSocket and HTTP endpoints are rate-limited
- **Channel Isolation**: Each API key can only access its own channels
- **Permission Controls**: Plugin-side controls for create/delete operations

## License

MIT