⚡ 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.

---

🏛️ System Architecture

┌─────────────────────────────────────────────────────────────┐
│             AI Client (Claude / Cursor / Antigravity / LLM) │
└──────────────────────────────┬──────────────────────────────┘
                               │ MCP Protocol (stdio / SSE)
                               ▼
┌─────────────────────────────────────────────────────────────┐
│        MCP Server (@figma-agent/mcp-server — 49 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 Transaction Pipeline  - Idempotency & Rollback     │
└──────────────────────────────┬──────────────────────────────┘
                               │ 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.
• 🧩 49 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.
• 🔄 Atomic Batch Execution: Sequential execution of command pipelines with stopOnFirstError or continueOnError error recovery.
• 🚀 Turnkey Agent Skills: Pre-packaged composite workflows for instant Design System generation, WCAG accessibility auto-repair, and wireframe-to-hifi card conversion.

---

📦 Monorepo Layout

figma-agent-mcp/
├── apps/
│   ├── mcp-server/        # 49 MCP Tools + Bridge Client + Session Service
│   ├── bridge-server/     # High-throughput WebSocket router (ws)
│   └── figma-plugin/      # Pure TypeScript native Figma Plugin
├── packages/
│   ├── protocol/          # CommandEnvelope, CommandResult, Error codes, Zod schemas
│   ├── figma-schema/      # SimplifiedNode, Layout, Style, Text, Validation schemas
│   ├── command-engine/    # Batch execution pipeline, transactions, ref resolution
│   ├── 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/     # Composite skills registry & execution engine
│   ├── telemetry/         # Percentile metrics collector (p50, p95, p99)
│   └── shared/            # Hex/RGBA converters, Pino logger, environment config
└── tests/
    └── integration/       # 27 Vitest suites covering all phases & stress benchmarks

---

🚀 Quickstart & Setup

1. Build the Monorepo

git clone https://github.com/your-org/figma-agent-mcp.git
cd figma-agent-mcp
pnpm install
pnpm build

2. Start the Bridge Server

pnpm --filter @figma-agent/bridge-server start
# Bridge server listening at ws://127.0.0.1:3055

3. Load the Figma Plugin in Figma Desktop

1. Open Figma Desktop.
2. Go to Plugins → Development → Import plugin from manifest...
3. Select apps/figma-plugin/manifest.json.
4. Run Figma Agent Bridge plugin. Note your Channel ID (defaults to default-channel).

---

⚙️ 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):

{
  "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):

{
  "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):

{
  "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):

{
  "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:

# 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:

{
  "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 (4 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	none	List all reusable components and variants in the file.
figma.get_local_styles	type (PAINT/TEXT/EFFECT/GRID)	List local paint, text, and effect styles.

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*	Delete a node from the canvas.
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	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 in an atomic transaction with symbolic reference resolution (ref, parentRef, nodeRef, $ref:name) and automatic failure rollback.

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

{
  "transactionId": "tx-pricing-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

1. skill.create_design_system

Creates a turnkey design system in seconds:

• Creates Variable Collection: Color Palette & Tokens.
• Creates variables: color/primary, color/background, color/surface, color/text-primary.
• Creates corresponding Paint Styles.
• Generates a responsive Button/Primary Master Component with Auto Layout, corner radius, and token bindings.

2. skill.auto_fix_accessibility

Audits the target layout hierarchy for WCAG 2.1 contrast violations and automatically repairs low-contrast text colors against their background surfaces to achieve AA compliance.

3. skill.convert_wireframe_to_hifi

Transforms a low-fidelity wireframe container into a polished, responsive High-Fidelity UI Card with Auto Layout, modern surface fills, soft drop shadows, and continuous corner smoothing.

---

🧪 Testing & Verification

Run the comprehensive test suite (115 passing tests across 27 test files):

# 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