# CC Fig MCP

Figma integration for Claude Code with bidirectional design control and real-time sync.

> Based on [claude-talk-to-figma-mcp-daisyui](https://github.com/morteng/claude-talk-to-figma-mcp-daisyui) by morteng and [claude-talk-to-figma-mcp](https://github.com/arinspunk/claude-talk-to-figma-mcp) by arinspunk.

## Prerequisites

- Node.js 18+
- Docker & Docker Compose
- pnpm
- Figma Desktop

## Build from Source

```bash
git clone https://github.com/agenisea/cc-fig-mcp.git
cd cc-fig-mcp
pnpm install
pnpm run build
```

## Setup Guide

### 1. Run the WebSocket Relay (Docker)

```bash
cd /path/to/cc-fig-mcp

# Build and start the relay server
docker-compose up -d --build

# Verify it's running
curl http://localhost:3055/status
```

### 2. Configure Claude Code

**Option A: CLI Flag**

```bash
claude --mcp-config '{"figma":{"command":"node","args":["/path/to/cc-fig-mcp/dist/talk_to_figma_mcp/server.js"]}}'
```

**Option B: Edit `~/.claude.json`**

```json
{
  "mcpServers": {
    "figma": {
      "command": "node",
      "args": [
        "/path/to/cc-fig-mcp/dist/talk_to_figma_mcp/server.js"
      ]
    }
  }
}
```

### 3. Install Figma Plugin

1. Open Figma Desktop
2. Go to **Plugins → Development → Import plugin from manifest**
3. Select: `/path/to/cc-fig-mcp/src/claude_mcp_plugin/manifest.json`

### 4. Connect Figma Plugin

1. In Figma, open **Plugins → CC Fig MCP Plugin**
2. Set **Port**: `3055`
3. Set **Channel**: Your Figma project name (e.g., `my-app-design`, `dashboard-ui`)
4. Click **Connect**
5. Status must show green/connected

### 5. Use in Claude Code

```bash
# Join the same channel as your Figma plugin (your Figma project name)
figma - join_channel("your-figma-project-name")

# Now you can use Figma tools
figma - create_rectangle(x: 0, y: 0, width: 100, height: 100)
figma - create_text(x: 50, y: 50, text: "Hello")
```

---

## Available Tools

| Tool | Description |
|------|-------------|
| `join_channel` | Connect to a Figma project channel |
| `get_document_info` | Get current document details |
| `get_selection` | Get selected nodes |
| `get_node_info` | Get details about specific nodes |
| `create_frame` | Create a frame/artboard |
| `create_rectangle` | Create a rectangle |
| `create_text` | Create text element |
| `create_ellipse` | Create an ellipse |
| `create_polygon` | Create a polygon |
| `create_star` | Create a star shape |
| `create_line` | Create a line |
| `create_component_instance` | Create instance of a component |
| `set_fill_color` | Change fill color |
| `set_stroke_color` | Change stroke color |
| `set_corner_radius` | Set corner radius |
| `set_text_content` | Update text content |
| `set_font_size` | Change font size |
| `set_font_weight` | Change font weight |
| `set_auto_layout` | Configure auto layout |
| `move_node` | Move a node |
| `resize_node` | Resize a node |
| `clone_node` | Duplicate a node |
| `delete_node` | Delete a node |
| `group_nodes` | Group nodes together |
| `ungroup_nodes` | Ungroup nodes |
| `export_node_as_image` | Export node as PNG/SVG |
| `get_styles` | Get document styles |
| `get_local_components` | Get local components |

---

## Important Requirements

| Requirement | Details |
|-------------|---------|
| Docker running | WebSocket relay must be up on port 3055 |
| Plugin window open | Keep the Figma plugin window visible |
| Connection green | Plugin must show connected status |
| Same channel | Use your Figma project name as the channel in both Figma plugin and Claude Code |
| Reconnect if needed | If you see timeouts, reconnect the plugin and re-join channel in Claude Code |

---

## Troubleshooting

### "Forwarded message to 0 clients"
Figma plugin disconnected. Reconnect in Figma.

### "Request timed out"
Plugin not connected or wrong channel. Check plugin status and channel name matches.

### "Must join a channel"
Run `join_channel("your-figma-project-name")` in Claude Code first.

### Port 3055 already in use
Change the port in `docker-compose.yml`:
```yaml
ports:
  - "3056:3055"  # Use 3056 externally
```
Then update the Figma plugin port to match.

### Connection drops frequently
The Figma plugin may disconnect when the plugin window loses focus. Keep the plugin panel visible while working.

---

## Architecture

```
Claude Code
    ↓ (stdio - MCP protocol)
MCP Server (server.js)
    ↓ (WebSocket ws://localhost:3055)
Docker Container (socket relay)
    ↓ (WebSocket)
Figma Plugin (inside Figma Desktop)
```

---

## Disclaimer

**Experimental Software**: This project is in active development and should be considered experimental. It is not production-ready and may contain bugs or breaking changes.

**No Warranty**: This software is provided "as is", without warranty of any kind, express or implied. Use at your own risk.

**Third-Party Notice**: This project is not affiliated with, endorsed by, or sponsored by Figma, Inc. or Anthropic, PBC. All trademarks belong to their respective owners.

## License

MIT