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

TypeScript Strict Tests MCP Tools License: MIT

🏛️ System Architecture

┌─────────────────────────────────────────────────────────────┐
│        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

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

git clone https://github.com/TrungLee003/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: go to Plugins → Development → Import plugin from manifest...
Select apps/figma-plugin/manifest.json.
Open the plugin: it will automatically generate a cryptographically secure 128-bit Channel ID & Secret pair.
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)

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

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

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

skill.inspect_design: Read comprehensive node hierarchy, bounds, styles, typography, layout properties, and design token binding recommendations.
skill.create_screen: Construct a complete responsive screen container with header bar, content area, Auto Layout, and Fill/Hug sizing rules.
skill.edit_selection: Batch mutate visual fills, strokes, opacity, corner radius, and text characters on currently selected canvas nodes.
skill.create_component: Create a reusable Master Component with Auto Layout, styling, and typed component property definitions.
skill.apply_design_system: Audit a node subtree and automatically apply recommended Variable token bindings (figma.bind_variable).
skill.validate_design: Run complete WCAG 2.1 contrast, Auto Layout, and token scale rules against a layout subtree.

⚡ Specialized Workflows (3)

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.
skill.auto_fix_accessibility: Audits layout hierarchy for WCAG 2.1 contrast violations and automatically repairs low-contrast text colors to achieve AA compliance.
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):

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

Figma Agent MCP