Skip to main content
Glama
deenesjakoruzh
TrungLee003

Figma Agent MCP

by TrungLee003
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

⚡ Figma Agent MCP

Figma를 위한 로컬 우선 AI 디자인 에이전트 via Model Context Protocol (MCP) → WebSocket Bridge → Native Figma Plugin

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 도구: 읽기, 생성, 변경, 자동 레이아웃, 시각적 스타일, 컴포넌트, 변수/토큰, 타이포그래피, 내보내기, 디자인 시스템 해석을 포괄적으로 지원합니다.

  • 🎯 의미론적 디자인 시스템 해석기: 사람의 의도("primary button", "#6366F1")를 지각 색상 거리($\Delta E$)와 자동화된 노드 감사를 통해 일치하는 컴포넌트 및 토큰에 연결합니다.

  • ⚡ 컨텍스트 컴파일러 및 가지치기: 방대한 노드 트리를 의미론적 마크다운 또는 컴팩트 DSL로 압축하며, 적응형 깊이 가지치기와 토큰 예산 적용을 100ms 이내에 수행합니다. 일반적으로 상당한 컨텍스트 감소를 달성하며, 테스트 시나리오에서 벤치마크 픽스처는 70% 이상의 감소를 보여줍니다.

  • 🛡️ 내장 검증 및 WCAG 2.1 엔진: 일반 텍스트, 큰 텍스트, UI 구성 요소에 대한 상대 휘도 및 대비비 계산(AA/AAA); 자동 레이아웃 린터; 4px/8px 토큰 그리드 감사기.

  • 🔄 원자적 배치 실행: stopOnFirstError 또는 continueOnError 오류 복구를 사용한 명령 파이프라인의 순차적 실행.

  • 🚀 턴키 에이전트 스킬: 디자인 시스템 즉시 생성, WCAG 접근성 자동 수리, 와이어프레임에서 하이파이 카드 변환을 위한 사전 패키지된 복합 워크플로우.

📦 모노레포 구조

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. 모노레포 빌드

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 데스크탑에서 Figma 플러그인 로드

  1. Figma 데스크탑을 엽니다.

  2. 플러그인 → 개발 → 매니페스트에서 플러그인 가져오기... 로 이동합니다.

  3. apps/figma-plugin/manifest.json을 선택합니다.

  4. Figma Agent Bridge 플러그인을 실행합니다. 채널 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 설정에 추가합니다 (설정 → 기능 → 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 스키마를 통해 엄격하게 타입이 지정되며, 결정론적으로 실행되고, 강력한 실패 메타데이터를 제공합니다.

1. 연결 및 세션 관리 (4개 도구)

도구 이름

매개변수

설명

figma.get_connection

없음

현재 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

없음

파일의 모든 재사용 가능한 컴포넌트와 변형을 나열합니다.

figma.get_local_styles

type (PAINT/TEXT/EFFECT/GRID)

로컬 페인트, 텍스트 및 효과 스타일을 나열합니다.

3. 노드 생성 (4개 도구)

도구 이름

매개변수

설명

figma.create_frame

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

선택적 자동 레이아웃이 있는 컨테이너 프레임을 생성합니다.

figma.create_text

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

신뢰할 수 있는 글꼴 로딩으로 텍스트 노드를 생성합니다.

figma.create_rectangle

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

사각형 벡터 노드를 생성합니다.

figma.create_section

width, height, x, y, name, parentId

섹션 구성 컨테이너를 생성합니다.

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 (Solid/Gradient/Image 채우기 배열)

배경 색상, 그라데이션 및 이미지를 적용합니다.

figma.set_strokes

nodeId, strokes, strokeWeight, strokeAlign

테두리 선, 두께 및 정렬을 적용합니다.

figma.set_corner_radius

nodeId, radius (숫자 또는 모서리별 객체), 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. 변수 및 디자인 토큰 (6개 도구)

도구 이름

매개변수

설명

figma.get_local_variables

collectionId

로컬 변수 및 토큰 컬렉션을 나열합니다.

figma.create_variable

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

시맨틱 디자인 토큰 변수를 생성합니다.

figma.set_variable_value

variableId, modeId, value*

특정 모드에 대한 변수 값을 업데이트합니다.

figma.bind_variable

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

노드 속성을 디자인 토큰 변수에 바인딩합니다.

figma.create_paint_style

name, paints, description

파일에 공유 페인트 스타일을 생성합니다.

(재사용된 검사)

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

자간(트래킹)을 설정합니다.

11. 컨텍스트 최적화 및 정리 (1개 도구)

도구 이름

매개변수

설명

figma.compile_context

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

토큰 예산 적용 및 간결한 DSL 표현으로 Figma 트리를 컴파일하고 압축합니다.

12. 검증 및 접근성 (2개 도구)

도구 이름

매개변수

설명

figma.validate_node

nodeId, rules, includeChildren

WCAG 2.1 대비, 자동 레이아웃 규칙, 토큰 스케일 및 레이어 명명 상태에 대한 노드 트리를 감사합니다.

figma.check_contrast

foreground, background, fontSize, isBold

WCAG 2.1 상대 휘도 및 대비비(AA/AAA)를 계산합니다.

13. 복합 스킬 및 배치 실행 (3개 도구)

도구 이름

매개변수

설명

figma.list_skills

없음

사용 가능한 고급 에이전트 스킬을 검색합니다.

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)를 지각적 $\Delta E$ 거리 및 노드 토큰 감사를 통해 일치하는 컴포넌트/토큰으로 시맨틱하게 해석합니다.

💡 예시: 1회 배치 호출로 계층적 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

몇 초 만에 턴키 디자인 시스템을 생성합니다:

  • 변수 컬렉션 생성: 색상 팔레트 및 토큰.

  • 변수 생성: color/primary, color/background, color/surface, color/text-primary.

  • 해당 페인트 스타일 생성.

  • 자동 레이아웃, 모서리 반경 및 토큰 바인딩이 적용된 반응형 Button/Primary 마스터 컴포넌트 생성.

2. skill.auto_fix_accessibility

대상 레이아웃 계층 구조에서 WCAG 2.1 대비 위반 사항을 감사하고, 배경 표면에 대해 대비가 낮은 텍스트 색상을 자동으로 수정하여 AA 준수를 달성합니다.

3. skill.convert_wireframe_to_hifi

저해상도 와이어프레임 컨테이너를 자동 레이아웃, 현대적인 표면 채우기, 부드러운 그림자 및 연속 모서리 스무딩이 적용된 세련된 고해상도 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 토큰 예산으로 6,111개 노드의 컨텍스트 컴파일: < 100ms 실행 시간, 벤치마크 시나리오에서 70% 이상 컨텍스트 감소.

  • 🛡️ 내결함성: 소켓 드롭아웃 시 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