Skip to main content
Glama
deenesjakoruzh
TrungLee003

Figma Agent MCP

by TrungLee003
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

⚡ Figma Agent MCP

面向 Figma 的本地优先 AI 设计代理，通过 Model Context Protocol (MCP) → WebSocket 桥接 → 原生 Figma 插件 实现。

使用确定性类型化工具、设计系统感知、token 压缩和开箱即用的组合工作流，原生检查、创建、修改、样式化、验证并优化 Figma 设计。

CI Status TypeScript Strict Tests MCP Tools License: MIT

🏛️ 系统架构

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

Related MCP server: figmind

🌟 核心亮点

  • 🔒 本地优先且安全：默认绑定到 127.0.0.1。128 位密钥通道配对。不在 Figma 内部执行任意 JavaScript。

  • 🧩 49 个确定性 MCP 工具：全面覆盖读取、创建、修改、自动布局、视觉样式、组件、变量/Token、排版、导出和设计系统解析。

  • 🎯 语义化设计系统解析器：将人类意图（"primary button"、"#6366F1"）与匹配的组件和 Token 连接起来，并利用感知色彩距离（$\Delta E$）和自动化节点审计。

  • ⚡ 上下文编译器与裁剪：将庞大的节点树压缩为语义化 Markdown 或紧凑型 DSL，具备自适应深度裁剪和 token 预算强制，耗时低于 100ms。通常可实现显著的上下文缩减；基准测试样例显示在测试场景中缩减超过 70%。

  • 🛡️ 内置验证与 WCAG 2.1 引擎：为普通文本、大号文本和 UI 组件计算相对亮度和对比度（AA/AAA）；自动布局检查器；4px/8px token 网格审计器。

  • 🔄 原子批量执行：按顺序执行命令管道，支持 stopOnFirstError 或 continueOnError 错误恢复。

  • 🚀 开箱即用的 Agent 技能：预打包的组合工作流，用于即时设计系统生成、WCAG 无障碍自动修复，以及线框图到高保真卡片的转换。

📦 Monorepo 布局

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

🚀 快速开始与设置

1. 构建 Monorepo

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

2. 启动桥接服务器

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

3. 在 Figma Desktop 中加载 Figma 插件

  1. 打开 Figma Desktop。

  2. 转到 插件 → 开发 → 从 manifest 导入插件...

  3. 选择 apps/figma-plugin/manifest.json。

  4. 运行 Figma Agent Bridge 插件。记下你的 Channel ID（默认为 default-channel）。

⚙️ AI 客户端配置

🤖 1. Claude Desktop

将以下内容添加到你的 claude_desktop_config.json（Windows 上为 %APPDATA%\Claude\claude_desktop_config.json，macOS 上为 ~/Library/Application Support/Claude/claude_desktop_config.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

添加到你的 Cursor MCP 配置（Settings → Features → MCP 或 .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

将以下内容添加到你的 Antigravity MCP 设置（~/.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

将以下内容添加到你的 Codex MCP 配置（~/.codex/config.json 或 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"
      }
    }
  }
}

或者通过 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

添加到 ~/.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"
      }
    }
  }
}

📚 完整 MCP 工具参考（50 个工具）

所有 50 个 MCP 工具均通过 Zod schema 进行严格类型化，确定性执行，并提供可靠的失败元数据。

1. 连接与会话管理（4 个工具）

工具名称

参数

描述

figma.get_connection

none

获取当前 WebSocket 桥接连接状态、延迟和会话能力。

figma.join_channel

channelId*, secret

切换或加入特定的 Figma 文档通道会话。

2. 检查与读取（6 个工具）

工具名称

参数

描述

figma.get_document

depth (0–10)

检索具有受限深度的文档根层级结构。

figma.get_selection

depth (0–10)

获取当前 Figma 画布中选中的节点。

figma.get_node

nodeId*, depth

读取特定节点的详细属性和子树。

figma.get_nodes

nodeIds*, depth

按 ID 批量获取多个节点。

figma.get_local_components

none

列出文件中所有可复用组件和变体。

figma.get_local_styles

type (PAINT/TEXT/EFFECT/GRID)

列出本地填充、文本和效果样式。

3. 节点创建（4 个工具）

工具名称

参数

描述

figma.create_frame

width, height, x, y, name, parentId, layoutMode

创建容器 Frame，可选 Auto Layout。

figma.create_text

text*, x, y, width, font ({family, style, size}), name, parentId

创建具有可靠字体加载功能的 Text 节点。

figma.create_rectangle

width, height, x, y, cornerRadius, name, parentId

创建 Rectangle 矢量节点。

figma.create_section

width, height, x, y, name, parentId

创建 Section 组织容器。

4. 节点修改与几何（6 个工具）

工具名称

参数

描述

figma.move_node

nodeId, x, y*

将节点移动到绝对坐标位置。

figma.resize_node

nodeId, width, height*

调整节点尺寸。

figma.rename_node

nodeId, name

重命名节点图层的标题。

figma.delete_node

nodeId*

从画布中删除节点。

figma.clone_node

nodeId*, parentId, x, y, name

复制现有节点层级结构。

figma.set_parent

nodeId, targetParentId, index

在图层树中重新设置父级并调整节点顺序。

5. 自动布局与响应式尺寸（2 个工具）

工具名称

参数

描述

figma.set_auto_layout

nodeId, mode, itemSpacing, padding ({top, right, bottom, left}), primaryAxisAlignItems, counterAxisAlignItems

配置响应式、类似 Flexbox 的自动布局。

figma.set_layout_sizing

nodeId*, horizontal (FIXED/HUG/FILL), vertical (FIXED/HUG/FILL)

设置容器和子对象的轴向尺寸行为。

6. 视觉样式与效果（5 个工具）

工具名称

参数

描述

figma.set_fills

nodeId, fills (Array of Solid/Gradient/Image fills)

应用背景颜色、渐变和图像。

figma.set_strokes

nodeId, strokes, strokeWeight, strokeAlign

应用边框描边、粗细和对齐方式。

figma.set_corner_radius

nodeId, radius (number or per-corner object), cornerSmoothing

设置边框圆角半径，支持 iOS 连续平滑。

figma.set_opacity

nodeId, opacity (0.0 – 1.0)

调整图层不透明度。

figma.set_effects

nodeId, effects (DROP_SHADOW, INNER_SHADOW, LAYER_BLUR)

应用投影、内阴影和模糊效果。

7. 组件与实例（5 个工具）

工具名称

参数

描述

figma.create_component

name*, width, height, parentId, componentPropertyDefinitions

将节点转换为可复用的主组件。

figma.create_instance

componentId*, x, y, properties, parentId

实例化组件变体。

figma.set_component_properties

nodeId, properties

覆盖组件变体属性。

figma.detach_instance

nodeId, destructive

将组件实例分离为常规可编辑帧（受安全保护）。

figma.get_local_components

query, pageOnly

获取本地主组件和带有变体属性的组件集。

8. 变量与 Design Token（6 个工具）

工具名称

参数

描述

figma.get_local_variables

collectionId

列出本地变量和 Token 集合。

figma.create_variable

name, resolvedType (COLOR/FLOAT/STRING/BOOLEAN), collectionId, collectionName, initialValue

创建语义化设计 Token 变量。

figma.set_variable_value

variableId, modeId, value*

更新指定模式的变量值。

figma.bind_variable

nodeId, property (fills/strokes/opacity/itemSpacing/cornerRadius), variableId*

将节点属性绑定到设计 Token 变量。

figma.create_paint_style

name, paints, description

在文件中创建共享的 Paint 样式。

(复用自 Inspect)

get_local_styles

查询共享样式。

9. 资源、图片与导出（3 个工具）

工具名称

参数

描述

figma.export_node

nodeId*, format (PNG/JPG/SVG/PDF), scale

将节点导出为 Base64 图片数据或 UTF-8 SVG 字符串。

figma.set_export_settings

nodeId, exportSettings

在节点上配置导出预设。

figma.set_image_fill

nodeId, imageBase64, scaleMode, opacity

从 Base64 上传并应用图片填充。

10. 文本与排版（6 个工具）

工具名称

参数

描述

figma.set_text_content

nodeId, text

更新文本字符串内容。

figma.set_font_size

nodeId, fontSize, start, end

更新字号（整段文本或指定范围）。

figma.set_font_family

nodeId, family, style, start, end

更改字体族和字重，并自动加载字体。

figma.set_text_alignment

nodeId*, horizontal (LEFT/CENTER/RIGHT/JUSTIFIED), vertical

设置文本对齐方式。

figma.set_line_height

nodeId*, unit (PIXELS/PERCENT/AUTO), value

设置行高间距。

figma.set_letter_spacing

nodeId, unit (PIXELS/PERCENT), value

设置字距（tracking）。

11. 上下文优化与剪枝（1 个工具）

工具名称

参数

描述

figma.compile_context

nodeId, format (markdown/dsl/compact/json), maxTokens, maxDepth

编译并压缩 Figma 树，支持 Token 预算强制和紧凑 DSL 表示。

12. 验证与无障碍（2 个工具）

工具名称

参数

描述

figma.validate_node

nodeId, rules, includeChildren

审计节点树的 WCAG 2.1 对比度、Auto Layout 规则、Token 尺度及图层命名健康度。

figma.check_contrast

foreground, background, fontSize, isBold

计算 WCAG 2.1 相对亮度和对比度（AA/AAA）。

13. 复合技能与批量执行（3 个工具）

工具名称

参数

描述

figma.list_skills

none

发现可用的高级智能体技能。

figma.run_skill

skillName*, payload

执行多步骤复合工作流。

figma.batch_execute

commands*, rollbackOnFailure (默认: true), stopOnFirstError, transactionId, idempotencyKey

在原子事务中执行多个 Figma 命令，支持符号引用解析（ref、parentRef、nodeRef、$ref:name）和失败自动回滚。

14. 设计系统语义解析（1 个工具）

工具名称

参数

描述

figma.resolve_design_system

type* (component/color/spacing/radius/audit_node), query, intentHint, nodeId

将人类意图（例如 "primary button"、"#6366F1"、16px）语义解析为匹配的组件/Token，并提供感知 $\Delta E$ 距离和节点 Token 审计。

💡 示例：在一次批量调用中构建层级化 UI 卡片

{
  "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" }] }
    }
  ]
}

返回 refMap: { "card": "123:456", "title": "123:457", "btn": "123:458" }。

🤖 复合智能体技能

1. skill.create_design_system

在几秒内创建开箱即用的设计系统：

  • 创建变量集合：调色板与 Token。

  • 创建变量：color/primary、color/background、color/surface、color/text-primary。

  • 创建对应的 Paint 样式。

  • 生成一个具有 Auto Layout、圆角半径和 Token 绑定的响应式 Button/Primary 主组件。

2. skill.auto_fix_accessibility

审计目标布局层级中的 WCAG 2.1 对比度违规项，并自动修复低对比度文本颜色与其背景表面的对比，以达到 AA 合规。

3. skill.convert_wireframe_to_hifi

将低保真线框容器转换为具有 Auto Layout、现代表面填充、柔和投影和连续圆角平滑的精致响应式高保真 UI 卡片。

🧪 测试与验证

运行全面的测试套件（27 个测试文件中共 115 个通过的测试）：

# 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

基准测试结果：

  • ⚡ WebSocket 并发：50 个并发客户端连接，带突发心跳：p95 < 100ms，0 掉线。

  • 🌳 大规模树扩展：在 1,000 Token 预算下对 6,111 个节点进行上下文编译：执行时间 < 100ms，基准场景中上下文缩减 >70%。

  • 🛡️ 容错性：在 Socket 掉线时通过 retryable 标志自动重连和处理错误。

📄 许可证

MIT © 2026 Figma Agent MCP Contributors

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Talk to Figma MCP

    hyun1202
    A
    license
    Not graded
    quality
    D
    maintenance
    An MCP server that enables AI assistants to interact with Figma designs for tasks like reading document info, creating elements, and managing auto layouts. It facilitates real-time design automation via a custom Figma plugin and WebSocket server integration.
    1,129 npm
    MIT

  • figmind

    guhcostan
    A
    license
    Not graded
    quality
    D
    maintenance
    MCP server that connects AI clients to Figma, enabling real-time reading, creation, and modification of designs using natural language.
    MIT