# 🎨 Figma MCP for Free Plan
https://smithery.ai/servers/haju-xp/figma-free-mcp

> Connect Claude to Figma with zero friction.
> No paid plan. No channel ID copy-paste. Just works.

[![npm](https://img.shields.io/npm/v/figma-free-mcp)](https://www.npmjs.com/package/figma-free-mcp)
[![smithery](https://img.shields.io/badge/smithery-figma--free--mcp-orange)](https://smithery.ai/server/haju-xp/figma-free-mcp)
[![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)

---

## ✨ Why this exists

| | Figma Official MCP | ClaudeTalkToFigma | **figma-free-mcp** |
|---|---|---|---|
| Free plan | ❌ Paid only | ✅ | ✅ |
| Auto-connect | ✅ | ❌ Manual channel ID | ✅ **Auto-detect** |
| Tools | Many | 70+ | **100+** |
| One-line install | ❌ | ❌ | ✅ |

---

## 🚀 Quick Start

### Step 1 — Install (once per PC)

```bash
npx -y figma-free-mcp@latest install
```

Or just tell Claude Code: **"피그마 설치해줘"** — after the first install the `/figma-connect` skill knows how.

This will:
- ✅ Register the MCP for **all folders** in Claude Code (`-s user`), pinned to this version
- ✅ Copy the Figma plugin to `~/.figma-free-mcp/plugin/` and open that folder
- ✅ Install the `/figma-connect` skill to `~/.claude/skills/`
- ✅ Clean up older setups (folder-only registrations, old global installs)

Run the same command again to **update**.

### Step 2 — Import the Figma plugin (once per PC)

Figma Desktop → **Plugins** → **Development** → **Import plugin from manifest...** → pick `manifest.json` in the folder Step 1 opened.

Then **restart Claude Code**.

### Every time

1. In Figma: **Plugins** → **Development** → **Figma Free MCP**
2. In Claude: `/figma-connect`

The relay server **starts by itself** when Claude connects — no terminal to keep open.

---

## 💬 Usage

Once everything is running, just talk to Claude naturally:

```
"Figma에 버튼 컴포넌트 만들어줘"
"중복 페이지 찾아서 정리해줘"
"globals.css 색상 토큰을 Figma 변수로 싱크해줘"
"이 React 컴포넌트를 Figma 프레임으로 변환해줘"
```

Claude automatically detects your open Figma file — **no channel ID needed!**

---

## 🗂️ Working with Multiple Files (Concurrent Editing)

Edit several Figma files in one session — still **no channel IDs**, just file names.

**Setup:** open each file and run the plugin in it (one plugin instance per file — a Figma limitation: a plugin can only touch the file it runs in).

```
"어떤 Figma 파일들이 열려 있어?"          → list_active_channels (shows file & page names)
"미들마일 주문 파일에 버튼 만들어줘"        → connect_to_file then edit, or run_on_file
"미들마일엔 헤더, 정산관리엔 합계 텍스트 넣어줘"  → runs on both files concurrently
```

| Tool | When to use |
|------|-------------|
| `connect_to_file("name")` | Focus one file — following commands all go there |
| `run_on_file("name", cmd, params)` | Send one command to a specific file **without** switching — repeat across files to edit them concurrently |

> ⚠️ Each file you want to edit must have its own running plugin instance. A file that's only open in the background (no plugin) cannot be edited.

---

## 🛠️ All Tools (100+)

### 🔌 Auto-Connect & Multi-File
| Tool | Description |
|------|-------------|
| `auto_connect` | Auto-detect active Figma sessions and connect |
| `list_active_channels` | List open Figma plugin sessions **with their file & page names** |
| `connect_to_file` | Connect by **file name** instead of channel ID (switches the active file) |
| `run_on_file` | Run one command on a specific file **without switching** — enables concurrent multi-file editing |

### 📄 Document & Pages
`get_document_info`, `get_pages`, `get_selection`, `get_node_info`, `get_nodes_info`, `scan_text_nodes`, `get_styles`, `get_local_components`, `get_remote_components`, `get_variables` and more

### 🖼️ Creation
`create_frame`, `create_rectangle`, `create_ellipse`, `create_text`, `create_page`, `create_component_from_node`, `create_component_instance`, `create_component_set` and more

### ✏️ Modification
`set_fill_color`, `set_stroke_color`, `set_text_content`, `set_font_size`, `set_corner_radius`, `set_auto_layout`, `move_node`, `resize_node`, `delete_node`, `clone_node` and more

### 🎨 Design System Sync
| Tool | Description |
|------|-------------|
| `sync_css_to_figma` | CSS variables → Figma variable collections |
| `sync_figma_to_css` | Figma variables → CSS custom properties |
| `compare_design_tokens` | Diff report between CSS and Figma |
| `apply_design_system` | Apply design policy doc to Figma |
| `audit_design_consistency` | Find policy violations in Figma file |

### 📋 Page Manager
| Tool | Description |
|------|-------------|
| `list_all_pages_detailed` | All pages + frame count + duplicate detection |
| `deduplicate_pages` | Auto-merge/remove duplicate pages |
| `organize_pages` | Sort pages by number or alphabetically |
| `cleanup_empty_pages` | Remove empty pages |

### ⚡ Code to Figma
| Tool | Description |
|------|-------------|
| `react_to_figma` | React/TSX component → Figma frame |
| `css_class_to_figma_style` | CSS classes → Figma local styles |
| `generate_component_variants` | Generate hover/active/disabled variants |

---

## 🏗️ Architecture

```
Claude Desktop
    │
    │ stdio (MCP)
    ▼
figma-free-mcp server (100+ tools)
    │
    │ WebSocket (port 3055)
    ▼
Figma Plugin (auto-connect)
    │
    │ Figma API
    ▼
Your Figma File ✨
```

---

## ⚙️ Commands Reference

```bash
npx -y figma-free-mcp@latest install    # install or update everything
npx -y figma-free-mcp@latest doctor     # what is installed and connected
npx -y figma-free-mcp@latest uninstall  # remove the Claude registration
npx -y figma-free-mcp@latest socket     # start the relay by hand (normally automatic)
```

---

## 🔄 Upgrading from v1.0.7 or earlier

─────────────────────────────

If you see a recurring **"MCP figma-free-mcp-socket: Server disconnected"** error in Claude Desktop, run this once:

```bash
npx -y figma-free-mcp@latest install
```

Then restart Claude Desktop. The error will be gone.

─────────────────────────────

---

## ❓ FAQ

**Q. Do I need a paid Figma plan?**
A. No. Works with free Figma accounts.

**Q. Do I need Claude Pro?**
A. Any Claude Desktop plan works.

**Q. The plugin shows "Disconnected"**
A. Run `/figma-connect` in Claude — it starts the relay if needed. Then re-run the plugin. Still stuck: `npx -y figma-free-mcp@latest doctor`

**Q. Multiple Figma files are open**
A. `list_active_channels` shows each session with its file & page name. Use `connect_to_file("name")` to focus one, or `run_on_file("name", ...)` to edit several files concurrently — no channel IDs needed. Each file must have its own running plugin instance.

**Q. Port 3055 is already in use**
A. Kill the existing process: `netstat -ano | findstr :3055` then `taskkill /PID [number] /F`

---

## ⚠️ License & Usage

MIT License — free to use and modify.

✅ Personal & commercial use allowed
✅ Modification allowed
❌ Claiming as your own work prohibited
❌ Removing author credit prohibited

© 2026 [haju-xp](https://github.com/haju-xp)

---

## 🙏 Credits

Built on top of [claude-talk-to-figma-mcp](https://github.com/arinspunk/claude-talk-to-figma-mcp) by arinspunk (MIT License).