Figma Agent MCP
by TrungLee003
README.md
# โก Figma Agent MCP
> **Local-first AI Design Agent for Figma** via **Model Context Protocol (MCP)** โ **WebSocket Bridge** โ **Native Figma Plugin**.
>
> Inspect, create, mutate, style, validate, and optimize Figma designs natively with deterministic typed tools, design-system awareness, token compression, and turnkey composite workflows.
[](https://github.com/TrungLee003/figma-agent-mcp/actions/workflows/ci.yml)
[](https://www.typescriptlang.org)
[](https://github.com/TrungLee003/figma-agent-mcp)
[](https://github.com/TrungLee003/figma-agent-mcp)
[](LICENSE)
---
## ๐๏ธ System Architecture
```text
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ AI Client (Claude / Cursor / Antigravity / LLM) โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ MCP Protocol (stdio / Hardened SSE)
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ MCP Server (@figma-agent/mcp-server โ 50 Tools) โ
โ - Tool Registry & Validation - Session Router โ
โ - Context Compiler (Compact) - Composite Skills Runtime โ
โ - Design System Resolver - Semantic Token Matching โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Command Engine (@figma-agent/command-engine) โ
โ - Batch Command Pipeline - Scoped Idempotency Cache โ
โ - Symbolic Ref Resolution - Compensating Node Cleanup โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Local WebSocket (ws://127.0.0.1:3055)
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Bridge Server (@figma-agent/bridge-server) โ
โ - Channel Pairing (128-bit) - Request/Response Matcher โ
โ - Heartbeat & Auto-reconnect - 50+ Concurrent Sockets โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Figma Plugin (@figma-agent/figma-plugin) โ
โ - Typed Command Dispatcher - Pure Font Engine โ
โ - Native Node Mutation - Zero External Dependencies โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Figma Plugin API
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Figma Canvas โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
```
---
## ๐ Key Highlights
- ๐ **Local-First & Secure**: Binds to `127.0.0.1` by default. 128-bit secret channel pairing. No arbitrary JavaScript execution inside Figma. Hardened SSE transport with Bearer token authentication and origin allowlists.
- ๐งฉ **50 Deterministic MCP Tools**: Comprehensive coverage across Read, Create, Mutate, Auto Layout, Visual Styles, Components, Variables/Tokens, Typography, Export, and Design System Resolution.
- ๐ฏ **Semantic Design-System Resolver**: Bridges human intent (`"primary button"`, `"#6366F1"`) to matching Components and Tokens with perceptual color distance ($\Delta E$) and automated node auditing.
- โก **Context Compiler & Pruning**: Compresses massive node trees into semantic Markdown or Compact DSL with adaptive depth pruning and token budget enforcement under 100ms. Typically achieves substantial context reduction; benchmark fixtures show >70% reduction in tested scenarios.
- ๐ก๏ธ **Built-in Validation & WCAG 2.1 Engine**: Relative luminance and contrast ratio calculation (AA/AAA) for normal text, large text, and UI components; Auto Layout linter; 4px/8px token grid auditor.
- ๐ **Sequential Batch Execution & Cleanup**: High-throughput execution of command pipelines with dynamic symbolic ref resolution, SHA-256 idempotency deduplication with conflict detection, and compensating creation rollback on failure.
- ๐ **Turnkey Agent Skills**: Pre-packaged composite workflows for instant Design System generation, WCAG accessibility auto-repair, and wireframe-to-hifi card conversion.
---
## ๐ฆ Monorepo Layout
```text
figma-agent-mcp/
โโโ apps/
โ โโโ mcp-server/ # 50 MCP Tools + Bridge Client + Session Service + Hardened SSE
โ โโโ bridge-server/ # High-throughput WebSocket router (ws) with 128-bit key pairing
โ โโโ figma-plugin/ # Pure TypeScript native Figma Plugin (IIFE bundle)
โโโ packages/
โ โโโ protocol/ # CommandEnvelope, CommandResult, Error codes, Zod schemas
โ โโโ figma-schema/ # Canonical FigmaCommandMap, Layout, Style, Text schemas
โ โโโ command-engine/ # Batch execution pipeline, transactions, scoped idempotency
โ โโโ context-compiler/ # Token optimizer, tree pruner, Markdown & DSL serializers
โ โโโ design-system/ # 4px/8px Spacing, Typography & Corner Radius scale matchers
โ โโโ validator/ # WCAG 2.1 contrast engine, Auto Layout & design token rules
โ โโโ skill-runtime/ # Strictly-typed composite skills runtime & execution engine
โ โโโ telemetry/ # Percentile metrics collector (p50, p95, p99)
โ โโโ shared/ # Hex/RGBA converters, Pino logger, host validation helpers
โโโ tests/
โโโ integration/ # 33 Vitest suites (171 tests) covering all phases & benchmarks
```
---
## ๐ Quickstart & Setup
### 1. Build the Monorepo
```bash
git clone https://github.com/TrungLee003/figma-agent-mcp.git
cd figma-agent-mcp
pnpm install
pnpm build
```
### 2. Start the Bridge Server
```bash
pnpm --filter @figma-agent/bridge-server start
# Bridge server listening at ws://127.0.0.1:3055
```
### 3. Load the Figma Plugin
1. In Figma Desktop: go to **Plugins** โ **Development** โ **Import plugin from manifest...**
2. Select `apps/figma-plugin/manifest.json`.
3. Open the plugin: it will automatically generate a cryptographically secure 128-bit Channel ID & Secret pair.
4. Click **๐ Copy Config** in the plugin window. The ready-to-use MCP client configuration snippet is copied directly to your clipboard.
### 4. Start the MCP Server (Stdio or Hardened SSE)
```bash
# Mode A: Stdio Transport (standard for Claude Desktop, Cursor, Antigravity)
pnpm --filter @figma-agent/mcp-server start
# Mode B: Hardened SSE Transport (HTTP Server-Sent Events with Bearer Auth & Loopback checks)
pnpm --filter @figma-agent/mcp-server start -- --sse --port=3056 --token=YOUR_BEARER_TOKEN
```
---
## โ๏ธ AI Client Configuration
### ๐ค 1. Claude Desktop
Add to your `claude_desktop_config.json` (`%APPDATA%\Claude\claude_desktop_config.json` on Windows or `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
```json
{
"mcpServers": {
"figma": {
"command": "node",
"args": ["d:/Code/Figma MCP/apps/mcp-server/dist/cli.js"],
"env": {
"FIGMA_AGENT_BRIDGE_HOST": "127.0.0.1",
"FIGMA_AGENT_BRIDGE_PORT": "3055",
"FIGMA_AGENT_CHANNEL_ID": "default-channel"
}
}
}
}
```
---
### ๐ป 2. Cursor IDE
Add to your Cursor MCP Configuration (`Settings` โ `Features` โ `MCP` or `.cursor/mcp.json`):
```json
{
"mcpServers": {
"figma-agent": {
"command": "node",
"args": ["d:/Code/Figma MCP/apps/mcp-server/dist/cli.js"],
"env": {
"FIGMA_AGENT_BRIDGE_HOST": "127.0.0.1",
"FIGMA_AGENT_BRIDGE_PORT": "3055",
"FIGMA_AGENT_CHANNEL_ID": "default-channel"
}
}
}
}
```
---
### ๐ง 3. Google Antigravity / Gemini CLI
Add to your Antigravity MCP settings (`~/.gemini/antigravity/mcp_config.json`):
```json
{
"mcpServers": {
"figma-agent": {
"command": "node",
"args": ["d:/Code/Figma MCP/apps/mcp-server/dist/cli.js"],
"env": {
"FIGMA_AGENT_BRIDGE_HOST": "127.0.0.1",
"FIGMA_AGENT_BRIDGE_PORT": "3055"
}
}
}
}
```
---
### โก 4. OpenAI Codex / Codex CLI / OpenAI Operator
Add to your Codex MCP configuration (`~/.codex/config.json` or `codex-settings.json`):
```json
{
"mcpServers": {
"figma-agent": {
"command": "node",
"args": ["d:/Code/Figma MCP/apps/mcp-server/dist/cli.js"],
"env": {
"FIGMA_AGENT_BRIDGE_HOST": "127.0.0.1",
"FIGMA_AGENT_BRIDGE_PORT": "3055",
"FIGMA_AGENT_CHANNEL_ID": "default-channel"
}
}
}
}
```
Or register via **Codex CLI**:
```bash
# Add Figma Agent MCP to Codex CLI
codex mcp add figma-agent -- node "d:/Code/Figma MCP/apps/mcp-server/dist/cli.js"
# Inspect available tools via MCP Inspector
npx @modelcontextprotocol/inspector node "d:/Code/Figma MCP/apps/mcp-server/dist/cli.js"
```
---
### ๐ 5. Windsurf / Codeium IDE
Add to `~/.codeium/windsurf/mcp_config.json`:
```json
{
"mcpServers": {
"figma-agent": {
"command": "node",
"args": ["d:/Code/Figma MCP/apps/mcp-server/dist/cli.js"],
"env": {
"FIGMA_AGENT_BRIDGE_HOST": "127.0.0.1",
"FIGMA_AGENT_BRIDGE_PORT": "3055",
"FIGMA_AGENT_CHANNEL_ID": "default-channel"
}
}
}
}
```
---
## ๐ Complete MCP Tools Reference (50 Tools)
All 50 MCP tools are strictly typed via Zod schemas, execute deterministically, and provide robust failure metadata.
### 1. Connection & Session Management (2 tools)
| Tool Name | Parameters | Description |
| ---------------------- | ---------------------- | ---------------------------------------------------------------------------------- |
| `figma.get_connection` | _none_ | Get current WebSocket bridge connection status, latency, and session capabilities. |
| `figma.join_channel` | `channelId`*, `secret` | Switch or join a specific Figma document channel session. |
### 2. Inspection & Read (6 tools)
| Tool Name | Parameters | Description |
| ---------------------------- | ------------------------------- | ----------------------------------------------------------------------- |
| `figma.get_document` | `depth` (0โ10) | Retrieve the document root hierarchy with bounded depth. |
| `figma.get_selection` | `depth` (0โ10) | Get currently selected nodes in the active Figma canvas. |
| `figma.get_node` | `nodeId`*, `depth` | Read detailed properties and subtree of a specific node. |
| `figma.get_nodes` | `nodeIds`*, `depth` | Batch fetch multiple nodes by ID. |
| `figma.get_local_components` | `query`, `pageOnly` | Retrieve local Master Components and Component Sets with variant props. |
| `figma.get_local_styles` | `type` (PAINT/TEXT/EFFECT/GRID) | List local paint, text, and effect styles with serialized paints. |
### 3. Node Creation (4 tools)
| Tool Name | Parameters | Description |
| ------------------------ | ------------------------------------------------------------------------------ | --------------------------------------------------- |
| `figma.create_frame` | `width`_, `height`_, `x`, `y`, `name`, `parentId`, `layoutMode` | Create a container Frame with optional Auto Layout. |
| `figma.create_text` | `text`*, `x`, `y`, `width`, `font` ({family, style, size}), `name`, `parentId` | Create a Text node with reliable font loading. |
| `figma.create_rectangle` | `width`_, `height`_, `x`, `y`, `cornerRadius`, `name`, `parentId` | Create a Rectangle vector node. |
| `figma.create_section` | `width`_, `height`_, `x`, `y`, `name`, `parentId` | Create a Section organization container. |
### 4. Node Mutation & Geometry (6 tools)
| Tool Name | Parameters | Description |
| ------------------- | ------------------------------------------ | ------------------------------------------------------- |
| `figma.move_node` | `nodeId`_, `x`_, `y`* | Move a node to absolute coordinate positions. |
| `figma.resize_node` | `nodeId`_, `width`_, `height`* | Resize node dimensions. |
| `figma.rename_node` | `nodeId`_, `name`_ | Rename node layer title. |
| `figma.delete_node` | `nodeId`_, `destructive`_ (must be `true`) | Permanently delete a node from canvas (safety guarded). |
| `figma.clone_node` | `nodeId`*, `parentId`, `x`, `y`, `name` | Duplicate an existing node hierarchy. |
| `figma.set_parent` | `nodeId`_, `targetParentId`_, `index` | Reparent and reorder a node in the layer tree. |
### 5. Auto Layout & Responsive Sizing (2 tools)
| Tool Name | Parameters | Description |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| `figma.set_auto_layout` | `nodeId`_, `mode`_, `itemSpacing`, `padding` ({top, right, bottom, left}), `primaryAxisAlignItems`, `counterAxisAlignItems` | Configure responsive Flexbox-like Auto Layout. |
| `figma.set_layout_sizing` | `nodeId`*, `horizontal` (FIXED/HUG/FILL), `vertical` (FIXED/HUG/FILL) | Set container and child axis sizing behavior. |
### 6. Visual Styles & Effects (5 tools)
| Tool Name | Parameters | Description |
| ------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------- |
| `figma.set_fills` | `nodeId`_, `fills`_ (Array of Solid/Gradient/Image fills) | Apply background colors, gradients, and images. |
| `figma.set_strokes` | `nodeId`_, `strokes`_, `strokeWeight`, `strokeAlign` | Apply border strokes, weights, and alignments. |
| `figma.set_corner_radius` | `nodeId`_, `radius`_ (number or per-corner object), `cornerSmoothing` | Set border corner radius with iOS continuous smoothing. |
| `figma.set_opacity` | `nodeId`_, `opacity`_ (0.0 โ 1.0) | Adjust layer opacity. |
| `figma.set_effects` | `nodeId`_, `effects`_ (DROP_SHADOW, INNER_SHADOW, LAYER_BLUR) | Apply drop shadows, inner shadows, and blurs. |
### 7. Components & Instances (5 tools)
| Tool Name | Parameters | Description |
| -------------------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `figma.create_component` | `name`*, `width`, `height`, `parentId`, `componentPropertyDefinitions` | Convert a node into a reusable Master Component. |
| `figma.create_instance` | `componentId`*, `x`, `y`, `properties`, `parentId` | Instantiate a component variant. |
| `figma.set_component_properties` | `nodeId`_, `properties`_ | Override component variant properties. |
| `figma.detach_instance` | `nodeId`_, `destructive`_ (must be `true`) | Detach component instance to regular editable frames (safety guarded). |
| `figma.get_local_components` | `query`, `pageOnly` | Retrieve local Master Components and Component Sets with variant props. |
### 8. Variables & Design Tokens (6 tools)
| Tool Name | Parameters | Description |
| --------------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| `figma.get_local_variables` | `collectionId` | List local variables and token collections. |
| `figma.create_variable` | `name`_, `resolvedType`_ (COLOR/FLOAT/STRING/BOOLEAN), `collectionId`, `collectionName`, `initialValue` | Create a semantic Design Token variable. |
| `figma.set_variable_value` | `variableId`_, `modeId`_, `value`* | Update variable value for a specific mode. |
| `figma.bind_variable` | `nodeId`_, `property`_ (fills/strokes/opacity/itemSpacing/cornerRadius), `variableId`* | Bind a node property to a Design Token variable. |
| `figma.create_paint_style` | `name`_, `paints`_, `description` | Create a shared Paint Style in the file. |
| _(Reused Inspect)_ | `get_local_styles` | Query shared styles. |
### 9. Assets, Images & Export (3 tools)
| Tool Name | Parameters | Description |
| --------------------------- | ------------------------------------------------- | ----------------------------------------------------- |
| `figma.export_node` | `nodeId`*, `format` (PNG/JPG/SVG/PDF), `scale` | Export node as Base64 image data or UTF-8 SVG string. |
| `figma.set_export_settings` | `nodeId`_, `exportSettings`_ | Configure export presets on a node. |
| `figma.set_image_fill` | `nodeId`_, `imageBase64`_, `scaleMode`, `opacity` | Upload and apply an image fill from Base64. |
### 10. Text & Typography (6 tools)
| Tool Name | Parameters | Description |
| -------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------- |
| `figma.set_text_content` | `nodeId`_, `text`_ | Update text string content. |
| `figma.set_font_size` | `nodeId`_, `fontSize`_, `start`, `end` | Update font size (whole text or range). |
| `figma.set_font_family` | `nodeId`_, `family`_, `style`, `start`, `end` | Change font family and weight with auto font-loading. |
| `figma.set_text_alignment` | `nodeId`*, `horizontal` (LEFT/CENTER/RIGHT/JUSTIFIED), `vertical` | Set text alignment. |
| `figma.set_line_height` | `nodeId`*, `unit` (PIXELS/PERCENT/AUTO), `value` | Set line height spacing. |
| `figma.set_letter_spacing` | `nodeId`_, `unit` (PIXELS/PERCENT), `value`_ | Set letter spacing (tracking). |
### 11. Context Optimization & Pruning (1 tool)
| Tool Name | Parameters | Description |
| ----------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `figma.compile_context` | `nodeId`, `format` (markdown/dsl/compact/json), `maxTokens`, `maxDepth` | Compile and compress Figma trees with token budget enforcement and compact DSL representation. |
### 12. Validation & Accessibility (2 tools)
| Tool Name | Parameters | Description |
| ---------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `figma.validate_node` | `nodeId`, `rules`, `includeChildren` | Audit node tree for WCAG 2.1 contrast, Auto Layout rules, token scales, and layer naming health. |
| `figma.check_contrast` | `foreground`_, `background`_, `fontSize`, `isBold` | Calculate WCAG 2.1 relative luminance and contrast ratio (AA/AAA). |
### 13. Composite Skills & Batch Execution (3 tools)
| Tool Name | Parameters | Description |
| --------------------- | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `figma.list_skills` | _none_ | Discover available high-level Agent Skills. |
| `figma.run_skill` | `skillName`*, `payload` | Execute a multi-step composite workflow. |
| `figma.batch_execute` | `commands`*, `rollbackOnFailure` (default: true), `stopOnFirstError`, `transactionId`, `idempotencyKey` | Execute multiple Figma commands sequentially with dynamic symbolic reference resolution (`ref`, `parentRef`, `nodeRef`, `$ref:name`), in-memory idempotency deduplication (`idempotencyKey`), and compensating cleanup of newly created nodes on failure. |
### 14. Design System Semantic Resolution (1 tool)
| Tool Name | Parameters | Description |
| ----------------------------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `figma.resolve_design_system` | `type`* (component/color/spacing/radius/audit_node), `query`, `intentHint`, `nodeId` | Semantically resolve human intent (e.g. "primary button", "#6366F1", 16px) to matching components/tokens with perceptual $\Delta E$ distance and node token auditing. |
#### ๐ก Example: Building a Hierarchical UI Card in 1 Batch Call
```json
{
"transactionId": "tx-pricing-01",
"idempotencyKey": "idem-card-01",
"rollbackOnFailure": true,
"commands": [
{
"command": "figma.create_frame",
"ref": "card",
"payload": { "width": 360, "height": 480, "name": "Pricing Card" }
},
{
"command": "figma.create_text",
"ref": "title",
"parentRef": "card",
"payload": { "text": "Pro Plan", "font": { "family": "Inter", "style": "Bold", "size": 24 } }
},
{
"command": "figma.create_rectangle",
"ref": "btn",
"parentRef": "card",
"payload": { "width": 312, "height": 44, "cornerRadius": 8, "name": "CTA Button" }
},
{
"command": "figma.set_fills",
"nodeRef": "btn",
"payload": { "fills": [{ "type": "SOLID", "color": "#3B82F6" }] }
}
]
}
```
_Returns `refMap: { "card": "123:456", "title": "123:457", "btn": "123:458" }`._
---
## ๐ค Composite Agent Skills (9 Skills)
### ๐งฑ Core General Skills (6)
1. **`skill.inspect_design`**: Read comprehensive node hierarchy, bounds, styles, typography, layout properties, and design token binding recommendations.
2. **`skill.create_screen`**: Construct a complete responsive screen container with header bar, content area, Auto Layout, and Fill/Hug sizing rules.
3. **`skill.edit_selection`**: Batch mutate visual fills, strokes, opacity, corner radius, and text characters on currently selected canvas nodes.
4. **`skill.create_component`**: Create a reusable Master Component with Auto Layout, styling, and typed component property definitions.
5. **`skill.apply_design_system`**: Audit a node subtree and automatically apply recommended Variable token bindings (`figma.bind_variable`).
6. **`skill.validate_design`**: Run complete WCAG 2.1 contrast, Auto Layout, and token scale rules against a layout subtree.
### โก Specialized Workflows (3)
7. **`skill.create_design_system`**: Turnkey generation of Color Variable tokens (`color/primary`, `color/background`, `color/surface`, `color/text-primary`), Paint Styles, and a responsive `Button/Primary` master component.
8. **`skill.auto_fix_accessibility`**: Audits layout hierarchy for WCAG 2.1 contrast violations and automatically repairs low-contrast text colors to achieve AA compliance.
9. **`skill.convert_wireframe_to_hifi`**: Transforms a low-fidelity wireframe container into a polished High-Fidelity UI Card with modern surface fills, soft drop shadows, and continuous corner smoothing.
---
## ๐งช Testing & Verification
Run the comprehensive test suite (171 passing tests across 33 test files):
```bash
# Run format checking
pnpm format:check
# Run full build
pnpm build
# Run unit and integration tests
pnpm test
# Strict TypeScript typechecking
pnpm typecheck
# ESLint audit
pnpm lint
```
### Benchmark Results:
- โก **WebSocket Concurrency**: 50 concurrent client connections with burst heartbeats: **p95 < 100ms**, 0 dropouts.
- ๐ณ **Massive Tree Scaling**: Context compilation of **6,111 nodes** with 1,000 token budget: **< 100ms execution time, >70% context reduction in benchmark scenarios**.
- ๐ก๏ธ **Fault Tolerance**: Automatic reconnection and error handling with `retryable` flags on socket dropouts.
---
## ๐ License
MIT ยฉ 2026 Figma Agent MCP Contributors
This server cannot be deployed
Maintenance
ActivitySlowing
ResponsivenessNo issues