Claude Talk to Figma MCP

@dusskapark의 Cursor Talk to Figma MCP를 기반으로, Claude Code 환경에 맞게 확장한 MCP(Model Context Protocol) 통합 프로젝트입니다. Claude Code에서 Figma 디자인을 읽고 프로그래밍 방식으로 수정할 수 있습니다.

배경

기존 Figma MCP의 한계

현재 Figma 연동 MCP는 크게 두 가지가 있으며, 각각 뚜렷한 한계를 가지고 있습니다.

Figma 공식 MCP 서버 — REST API 기반의 읽기 전용 서버입니다.

• 디자인을 읽기만 가능하고, 생성이나 수정은 불가
• REST API + Personal Access Token 필요
• 무료 플랜은 월 6회 호출 제한, 유료 플랜도 분당 호출 제한 존재
• 주 용도: Figma 디자인을 코드로 변환할 때 컨텍스트 제공

Cursor Talk to Figma MCP — Plugin API 기반의 양방향 서버입니다.

• 디자인 읽기 + 수정이 가능하지만, 40개 도구로 기본 조작에 한정
• 사각형·프레임·텍스트 생성, 색상 변경, 레이아웃 등 기초 기능 중심
• 변수 시스템, 고급 스타일, 이펙트, 그라디언트 등 미지원
• 디자인 시스템 단위의 작업이나 브라우저 UI 캡처 불가

이 프로젝트가 추가한 것

이 프로젝트는 Cursor Talk to Figma MCP의 40개 도구를 94개로 확장하여, AI 에이전트가 디자이너 수준의 Figma 작업을 수행할 수 있도록 합니다.

| 영역 | 기존 MCP | 이 프로젝트 | |---|---|---| | 도형 생성 | 사각형, 프레임, 텍스트 | + 타원, 선, 다각형, 별, 벡터, 컴포넌트, 섹션 | | 스타일링 | 채우기, 스트로크, 모서리 | + 그라디언트, 이미지 채우기, 이펙트(그림자·블러), 블렌드 모드, 투명도, 회전 | | 스타일 관리 | — | 페인트·텍스트·이펙트·그리드 스타일 생성 및 적용 | | 텍스트 | 내용 수정만 가능 | + 폰트 로드, 범위별 스타일링(크기·색상·자간·행간) | | 변수 시스템 | — | 컬렉션·변수 CRUD, 모드 관리, 노드 바인딩 (10개 도구) | | 노드 제어 | 이동, 크기, 삭제 | + 가시성, 잠금, 제약조건, 부모 변경, 불리언 연산, 그룹핑 | | 디자인 생성 | 개별 노드 하나씩 | generate_figma_design: JSON 트리로 전체 UI 한번에 생성 | | 디자인 분석 | — | get_design_context: React+Tailwind 포맷 추출, create_design_system_rules: 디자인 시스템 규칙 생성 | | 브라우저 → Figma | — | send_ui_to_figma: 라이브 URL을 편집 가능한 Figma 레이어로 변환 | | Code Connect | — | Figma 컴포넌트 ↔ 코드 파일 매핑 (4개 도구) |

아키텍처

graph LR
    A["Claude Code<br/>(AI Agent)"] <-->|stdio| B["MCP 서버<br/>(server.ts)"]
    B <-->|WebSocket| C["WebSocket 중계 서버<br/>(socket.ts)"]
    C <-->|"port:3055"| D["Figma 플러그인<br/>(figma_plugin/)"]

graph LR
    subgraph send_ui_to_figma
    direction LR
    E["URL"] --> F["Playwright"] --> G["DOM 추출"] --> H["DesignTreeNode JSON"] --> I["Figma 레이어"]
    end

프로젝트 구조

• src/talk_to_figma_mcp/server.ts - Figma 연동을 위한 TypeScript MCP 서버
• src/talk_to_figma_mcp/dom-extractor.ts - 브라우저 DOM 추출 및 CSS → Figma 매핑 엔진
• src/figma_plugin/ - Figma와 통신하는 Figma 플러그인
• src/socket.ts - MCP 서버와 Figma 플러그인 간 통신을 중계하는 WebSocket 서버

설치 방법

방법 1: Claude Code 플러그인 (권장)

플러그인으로 설치하면 MCP 서버와 디자인 전략 스킬이 함께 설치됩니다.

# 1. 마켓플레이스 등록
claude plugin marketplace add https://github.com/letsur-dev/figma-mcp-for-claude

# 2. 플러그인 설치
claude plugin install talk-to-figma

설치 후 사용 가능한 스킬:

• /talk-to-figma:design-strategy — Figma 디자인 작업 모범 사례
• /talk-to-figma:read-design — Figma 디자인 읽기 모범 사례
• /talk-to-figma:text-replacement — 텍스트 교체 전략
• /talk-to-figma:annotation-conversion — 주석 변환 전략
• /talk-to-figma:swap-overrides — 오버라이드 전파 전략
• /talk-to-figma:reaction-to-connector — 리액션→커넥터 변환 전략

로컬에서 플러그인을 테스트하려면:

claude --plugin-dir /path/to/figma-mcp-for-claude

방법 2: MCP 서버 직접 등록

MCP 서버만 등록하려면 (스킬 없이 도구만 사용):

claude mcp add figma-mcp-for-claude -- bunx figma-mcp-for-claude@latest

시작하기

1. Bun 설치 (미설치 시):

curl -fsSL https://bun.sh/install | bash

2. 의존성 설치:

bun install
bun run build

3. Figma 플러그인 설치:

   1. Figma에서 Plugins > Development > Import plugin from manifest
   2. src/figma_plugin/manifest.json 파일 선택

4. (선택) 브라우저 UI 캡처 기능을 사용하려면 Playwright 설치:

npx playwright install chromium

5. 실행 (터미널 2개 필요):

┌─ 터미널 1: WebSocket 서버 ─────────────────────────────────┐
│ $ bun socket                                                │
│ WebSocket server running on port 3055                       │
└─────────────────────────────────────────────────────────────┘

┌─ 터미널 2: Claude Code ────────────────────────────────────┐
│ $ claude                                                    │
│ > "Figma에서 빨간색 버튼을 만들어줘"                          │
└─────────────────────────────────────────────────────────────┘

1. 터미널 1: bun socket으로 WebSocket 서버 시작 (항상 실행 상태 유지)
2. Figma: 플러그인 실행 → Connect 클릭 → 화면에 표시되는 채널 코드 확인
3. 터미널 2: Claude Code 실행 → join_channel로 채널 코드를 전달하여 연결
4. 연결 완료 후 Claude Code에서 Figma 조작 명령 사용 가능

디자인 자동화 예시

텍스트 일괄 교체

원본 프로젝트에 포함된 텍스트 일괄 교체 기능입니다. 데모 영상을 참고하세요.

인스턴스 오버라이드 전파

원본 프로젝트에 포함된 기능입니다. 소스 인스턴스의 컴포넌트 오버라이드를 여러 타겟 인스턴스에 한 번에 전파할 수 있습니다. 컴포넌트 인스턴스에 유사한 커스터마이징이 필요할 때 반복 작업을 크게 줄여줍니다. 데모 영상을 확인하세요.

브라우저 UI → Figma 레이어 변환

send_ui_to_figma 도구를 사용하면 브라우저에서 실행 중인 UI를 스크린샷이 아닌 편집 가능한 Figma 레이어로 변환할 수 있습니다. Playwright로 DOM 구조와 계산된 CSS 스타일을 추출하여 Figma 노드를 생성합니다.

• flex/grid 레이아웃 → Figma 오토 레이아웃
• 텍스트 스타일, 색상, 그림자, border-radius 보존
• <img>, <canvas>, <svg>, background-image 캡처
• localhost, staging, production URL 모두 지원

개발 환경 설정

개발 시 MCP 설정을 로컬 디렉토리로 지정합니다.

claude mcp add figma-mcp-for-claude -- bun /path-to-repo/src/talk_to_figma_mcp/server.ts

수동 설정 및 설치

MCP 서버: Claude Code 연동

Claude Code에 MCP 서버를 등록합니다:

claude mcp add figma-mcp-for-claude -- bunx figma-mcp-for-claude@latest

WebSocket 서버

WebSocket 서버를 시작합니다:

bun socket

Figma 플러그인

1. Figma에서 Plugins > Development > Import plugin from manifest
2. src/figma_plugin/manifest.json 파일 선택
3. Figma 개발 플러그인 목록에서 사용 가능

Windows + WSL 가이드

1. PowerShell에서 Bun 설치:

powershell -c "irm bun.sh/install.ps1|iex"

2. src/socket.ts에서 hostname 0.0.0.0 주석 해제:

// Windows WSL에서 연결을 허용하려면 주석 해제
hostname: "0.0.0.0",

3. WebSocket 시작:

bun socket

사용 방법

터미널 2개가 필요합니다: WebSocket 서버용 + Claude Code용

1. 터미널 1 — WebSocket 서버 시작 (bun socket), 세션 동안 계속 실행
2. Figma — Claude Talk to Figma 플러그인 실행 → Connect 클릭
3. 플러그인 UI에 표시된 채널 코드 확인 (예: abc123)
4. 터미널 2 — Claude Code 실행, join_channel로 채널 코드 전달하여 Figma와 연결
5. 연결 완료 후 Claude Code에서 MCP 도구로 Figma 조작

MCP 도구 목록 (총 94개)

MCP 서버가 제공하는 Figma 조작 도구 전체 목록입니다.

문서 & 선택 (8개)

| 도구 | 설명 | |---|---| | get_document_info | 현재 Figma 문서 정보 조회 | | get_selection | 현재 선택 영역 정보 조회 | | read_my_design | 현재 선택의 상세 노드 정보를 파라미터 없이 조회 | | get_node_info | 특정 노드의 상세 정보 조회 | | get_nodes_info | 여러 노드의 상세 정보를 노드 ID 배열로 일괄 조회 | | get_metadata | 경량 문서 구조 스캔 (id, name, type, 위치, 크기, 가시성만 반환) | | set_focus | 특정 노드를 선택하고 뷰포트를 이동하여 포커스 | | set_selections | 여러 노드를 선택하고 뷰포트에 표시 |

주석 (4개)

| 도구 | 설명 | |---|---| | get_annotations | 문서 또는 특정 노드의 모든 주석 조회 | | set_annotation | 마크다운 지원 주석 생성 또는 수정 | | set_multiple_annotations | 여러 주석 일괄 생성/수정 | | scan_nodes_by_types | 특정 타입의 노드 검색 (주석 대상 찾기에 유용) |

프로토타이핑 & 연결 (3개)

| 도구 | 설명 | |---|---| | get_reactions | 노드의 프로토타입 리액션 조회 (시각적 하이라이트 애니메이션 포함) | | set_default_connector | FigJam 커넥터 스타일을 기본값으로 설정 (연결 생성 전 필수) | | create_connections | 프로토타입 플로우 또는 커스텀 매핑 기반의 FigJam 커넥터 라인 생성 |

기본 도형 생성 (3개)

| 도구 | 설명 | |---|---| | create_rectangle | 사각형 생성 (위치, 크기, 이름 지정) | | create_frame | 프레임 생성 (위치, 크기, 이름 지정) | | create_text | 텍스트 노드 생성 (폰트 속성 커스터마이징) |

확장 도형 생성 (7개)

| 도구 | 설명 | |---|---| | create_ellipse | 타원/원 생성 (위치, 크기, 이름, 부모 노드 지정) | | create_line | 두 점 사이의 선 생성 (시작점, 끝점, 색상, 두께 지정) | | create_polygon | 정다각형 생성 (꼭짓점 수 3 이상, 크기 지정) | | create_star | 별 모양 생성 (꼭짓점 수, 내부 반지름 비율 지정) | | create_vector | SVG 패스 데이터로 벡터 경로 생성 | | create_component | 새 컴포넌트 생성 (위치, 크기 지정, key 반환) | | create_section | 현재 페이지에 섹션 생성 (페이지 레벨 컨테이너) |

이미지 & SVG 생성 (2개)

| 도구 | 설명 | |---|---| | create_node_from_svg | SVG 문자열로 노드 생성 | | create_image | Base64 인코딩 이미지 데이터로 이미지 노드 생성 |

페이지 관리 (1개)

| 도구 | 설명 | |---|---| | create_page | 새 페이지 생성 (이름 지정, 현재 페이지로 전환 옵션) |

불리언 & 그룹 연산 (4개)

| 도구 | 설명 | |---|---| | group_nodes | 여러 노드를 그룹으로 묶기 (같은 부모 필수) | | ungroup_nodes | 그룹 해제 (자식 노드를 부모로 이동) | | boolean_operation | 불리언 연산 수행 (UNION/SUBTRACT/INTERSECT/EXCLUDE) | | flatten_nodes | 여러 노드를 단일 벡터로 병합 |

텍스트 내용 수정 (3개)

| 도구 | 설명 | |---|---| | scan_text_nodes | 대용량 디자인을 위한 청크 기반 텍스트 노드 스캔 | | set_text_content | 단일 텍스트 노드 내용 설정 | | set_multiple_text_contents | 여러 텍스트 노드 일괄 수정 |

텍스트 스타일링 (3개)

| 도구 | 설명 | |---|---| | list_available_fonts | 사용 가능한 폰트 목록 조회 (검색 필터, 개수 제한) | | load_font | 텍스트에 사용할 폰트 로드 (family, style 지정) | | set_text_style_range | 텍스트 노드의 특정 문자 범위에 스타일 적용 (폰트, 크기, 색상, 장식, 행간, 자간) |

오토 레이아웃 & 간격 (5개)

| 도구 | 설명 | |---|---| | set_layout_mode | 프레임의 레이아웃 모드 설정 (NONE/HORIZONTAL/VERTICAL) | | set_padding | 오토 레이아웃 프레임의 패딩 설정 (상/우/하/좌) | | set_axis_align | 오토 레이아웃 프레임의 축 정렬 설정 | | set_layout_sizing | 오토 레이아웃 크기 모드 설정 (FIXED/HUG/FILL) | | set_item_spacing | 오토 레이아웃 자식 간 간격 설정 |

기본 스타일 (3개)

| 도구 | 설명 | |---|---| | set_fill_color | 노드의 채우기 색상 설정 (RGBA) | | set_stroke_color | 노드의 스트로크 색상 및 두께 설정 | | set_corner_radius | 노드의 모서리 반경 설정 (개별 모서리 제어 가능) |

노드 속성 (7개)

| 도구 | 설명 | |---|---| | set_opacity | 노드 투명도 설정 (0-1) | | set_rotation | 노드 회전 설정 (도 단위, 반시계 방향) | | set_blend_mode | 노드 블렌드 모드 설정 (NORMAL, MULTIPLY, SCREEN 등 18종) | | set_visibility | 노드 표시/숨기기 설정 | | set_locked | 노드 잠금/해제 설정 | | set_constraints | 노드의 리사이즈 제약 조건 설정 (MIN/CENTER/MAX/STRETCH/SCALE) | | reparent_node | 노드를 다른 부모로 이동 (인덱스 위치 지정 가능, 순환 참조 검증) |

이펙트 (1개)

| 도구 | 설명 | |---|---| | set_effects | 노드에 이펙트 설정 (DROP_SHADOW, INNER_SHADOW, LAYER_BLUR, BACKGROUND_BLUR) |

고급 채우기 (2개)

| 도구 | 설명 | |---|---| | set_gradient_fill | 노드에 그라디언트 채우기 설정 (LINEAR/RADIAL/ANGULAR/DIAMOND, 색상 정지점, 핸들 위치) | | set_image_fill | 노드에 이미지 채우기 설정 (Base64 이미지, 스케일 모드 FILL/FIT/CROP/TILE) |

스타일 관리 (5개)

| 도구 | 설명 | |---|---| | create_paint_style | 새 페인트 스타일 생성 (이름, RGBA 색상) | | set_paint_style | 노드에 기존 페인트 스타일 적용 (스타일 ID로 지정) | | create_text_style | 새 텍스트 스타일 생성 (폰트, 크기, 행간, 자간) | | create_effect_style | 새 이펙트 스타일 생성 (그림자, 블러 등) | | create_grid_style | 새 그리드 스타일 생성 (GRID/COLUMNS/ROWS 패턴) |

레이아웃 & 정리 (5개)

| 도구 | 설명 | |---|---| | move_node | 노드를 새 위치로 이동 | | resize_node | 노드 크기 변경 | | delete_node | 노드 삭제 | | delete_multiple_nodes | 여러 노드 일괄 삭제 | | clone_node | 노드 복제 (위치 오프셋 옵션) |

컴포넌트 & 스타일 (6개)

| 도구 | 설명 | |---|---| | get_styles | 로컬 스타일 정보 조회 | | get_local_components | 로컬 컴포넌트 정보 조회 | | get_component_spec | 컴포넌트 노드의 구현용 스펙 추출 (오토 레이아웃, 변수 바인딩, 시각 속성 포함) | | create_component_instance | 컴포넌트 인스턴스 생성 | | get_instance_overrides | 선택된 컴포넌트 인스턴스의 오버라이드 속성 추출 | | set_instance_overrides | 타겟 인스턴스에 오버라이드 적용 |

변수 시스템 (10개)

| 도구 | 설명 | |---|---| | get_local_variable_collections | 현재 파일의 모든 변수 컬렉션 조회 (모드, 변수 ID 포함) | | get_local_variables | 현재 파일의 모든 변수 조회 (타입별 필터링 가능) | | get_bound_variables | 노드에 바인딩된 변수 조회 | | create_variable_collection | 새 변수 컬렉션 생성 | | create_variable | 변수 컬렉션에 새 변수 생성 | | update_variable | 변수 값 업데이트 | | update_variable_collection | 변수 컬렉션 업데이트 | | manage_collection_modes | 컬렉션 모드 관리 | | bind_variable_to_node | 노드에 변수 바인딩 | | delete_variables | 변수 삭제 |

디자인 생성 & 분석 (3개)

| 도구 | 설명 | |---|---| | generate_figma_design | 구조화된 JSON 트리로 완전한 Figma 디자인 생성 (프레임, 텍스트, 도형, 이미지, 컴포넌트, 오토 레이아웃 지원) | | get_design_context | Figma 노드의 디자인 컨텍스트를 프레임워크별 포맷으로 추출 (React + Tailwind CSS: flex 클래스, 패딩, 타이포그래피, 색상, 변수 바인딩) | | create_design_system_rules | 현재 Figma 파일의 변수, 스타일, 컴포넌트에서 디자인 시스템 규칙 마크다운 생성 |

브라우저 UI 캡처 (1개)

| 도구 | 설명 | |---|---| | send_ui_to_figma | 브라우저 URL의 라이브 UI를 편집 가능한 Figma 레이어로 변환 (Playwright로 DOM + CSS 추출 → Figma 노드 생성) |

Code Connect (4개)

| 도구 | 설명 | |---|---| | get_code_connect_map | Figma 파일의 Code Connect 매핑(dev resource) 조회 (FIGMA_PERSONAL_ACCESS_TOKEN 필요) | | add_code_connect_map | Figma 노드에 코드-디자인 매핑(dev resource) 추가 (FIGMA_PERSONAL_ACCESS_TOKEN 필요) | | get_code_connect_suggestions | Figma 컴포넌트명과 로컬 코드 파일의 이름 유사도 기반 매핑 제안 | | send_code_connect_mappings | 확인된 Code Connect 매핑을 Figma 파일에 일괄 적용 (FIGMA_PERSONAL_ACCESS_TOKEN 필요) |

뷰포트 & 유틸리티 (2개)

| 도구 | 설명 | |---|---| | set_viewport | 뷰포트 중심 좌표 및 줌 레벨 설정 | | get_selection_colors | 현재 선택 영역에 사용된 모든 색상 조회 |

내보내기 (1개)

| 도구 | 설명 | |---|---| | export_node_as_image | 노드를 이미지로 내보내기 (PNG, JPG, SVG, PDF) |

연결 관리 (1개)

| 도구 | 설명 | |---|---| | join_channel | Figma와 통신할 특정 채널에 참가 |

MCP 프롬프트

복잡한 디자인 작업을 안내하는 헬퍼 프롬프트들입니다:

| 프롬프트 | 설명 | |---|---| | design_strategy | Figma 디자인 작업 모범 사례 | | read_design_strategy | Figma 디자인 읽기 모범 사례 | | text_replacement_strategy | 텍스트 교체를 위한 체계적 접근 방법 | | annotation_conversion_strategy | 수동 주석을 Figma 네이티브 주석으로 변환하는 전략 | | swap_overrides_instances | 컴포넌트 인스턴스 간 오버라이드 전달 전략 | | reaction_to_connector_strategy | 프로토타입 리액션을 커넥터 라인으로 변환하는 전략 |

개발

Figma 플러그인 빌드

1. Figma 플러그인 디렉토리로 이동:

   cd src/figma_plugin

2. code.js와 ui.html 편집

MCP 서버 빌드

bun run build

dist/server.js와 dist/server.cjs가 생성됩니다.

모범 사례

Figma MCP 사용 시 권장 사항:

1. 명령 전송 전 반드시 채널에 참가 (join_channel)
2. get_document_info로 문서 전체 구조 먼저 파악
3. 수정 전 get_selection으로 현재 선택 상태 확인
4. 용도에 맞는 생성 도구 사용:
   • create_frame — 컨테이너
   • create_rectangle — 기본 도형
   • create_ellipse — 타원/원
   • create_polygon — 정다각형
   • create_star — 별 모양
   • create_text — 텍스트 요소
   • create_component — 재사용 가능한 컴포넌트
   • create_section — 페이지 레벨 섹션
   • generate_figma_design — JSON 트리로 전체 UI 한번에 생성
5. get_node_info로 변경 사항 확인
6. 일관성을 위해 가능하면 컴포넌트 인스턴스 사용
7. 모든 명령은 예외를 발생시킬 수 있으므로 적절한 에러 처리 필요
8. 대용량 디자인의 경우:
   • scan_text_nodes의 청크 파라미터 활용
   • WebSocket을 통한 진행 상태 모니터링
   • 적절한 에러 처리 구현
9. 텍스트 작업 시:
   • 가능하면 일괄 작업 사용
   • set_text_style_range로 부분 스타일링 적용 가능
   • 타겟 내보내기로 변경 사항 확인
10. 레거시 주석 변환 시:
    • scan_text_nodes로 번호 마커와 설명 텍스트 식별
    • scan_nodes_by_types로 주석 대상 UI 요소 검색
    • 경로, 이름, 근접성으로 마커와 대상 요소 매칭
    • get_annotations로 주석 분류
    • set_multiple_annotations로 네이티브 주석 일괄 생성
    • 모든 주석이 대상에 올바르게 연결되었는지 확인
    • 변환 성공 후 레거시 주석 노드 삭제
11. 프로토타입 흐름을 FigJam 커넥터로 시각화:
    • get_reactions로 프로토타입 플로우 추출
    • set_default_connector로 기본 커넥터 스타일 설정
    • create_connections로 커넥터 라인 생성
12. 브라우저 UI를 Figma로 가져오기:
    • send_ui_to_figma로 URL의 라이브 UI 캡처
    • Playwright가 DOM 구조와 CSS를 자동 추출
    • flex/grid → 오토 레이아웃, 텍스트/색상/그림자/이미지 보존
    • selector 옵션으로 특정 컴포넌트만 캡처 가능

라이선스

MIT