04 Figma MCP 가이드
1. Figma MCP 가이드
Figma MCP(Model Context Protocol)를 활용하면 피그마 디자인 파일을 AI가 직접 분석하여 HTML/CSS 코드로 변환할 수 있다.
공식문서프롬프트안내
1.1. GeminiCli 로 연결하기
1.1.1. Gemini CLI 실행
1gemini1.1.2. 익스텐션 설치 명령 실행
터미널에서 Gemini CLI 세션을 종료한 상태에서 아래 명령을 실행한다.
1gemini extensions install https://github.com/figma/figma-gemini-cli-extension| 코드 | 설명 |
|---|---|
gemini extensions install | Gemini CLI에 익스텐션을 설치하는 명령 |
https://github.com/... | 설치할 익스텐션의 GitHub 저장소 주소 |
참고
익스텐션은 ~/.gemini/extensions/ 폴더 아래에 저장된다. 로컬에 코드가 설치되는 것이 아니라, Figma의 원격 MCP 서버(mcp.figma.com/mcp)에 연결하는 설정 파일이 저장되는 방식이다.
1.1.3. 설치 확인
Gemini CLI를 실행한 뒤 아래 명령으로 등록된 MCP 서버 목록을 확인한다.
1gemini1/mcp listfigma가 목록에 표시되면 설치가 완료된 것이다.
MCP를 통해 Figma 파일에 접근하려면 Figma API(에이피아이) 인증에 사용할 개인 액세스 토큰(Personal Access Token(퍼스널 액세스 토큰))을 발급해야 한다.
1.1.4. Figma 설정 진입
- 브라우저에서 https://www.figma.com에 접속해 로그인한다.
- 우측 상단 **프로필 아바타(아바타: 계정 아이콘)**를 클릭한다.
- 드롭다운(드롭다운: 펼침 메뉴)에서 Settings(세팅) 를 클릭한다.
1.1.5. Security(시큐리티) 탭으로 이동
Settings 화면 상단 탭에서 Security(시큐리티: 보안) 탭을 클릭한다. 아래로 스크롤하면 Personal access tokens(퍼스널 액세스 토큰) 섹션이 나타난다.
1.1.6. 새 토큰 생성
- Generate new token(제너레이트 뉴 토큰) 버튼을 클릭한다.
- 토큰 이름을 입력한다. (예:
gemini-mcp) - 토큰의 만료 기간을 선택한다.
- 스코프(스코프: 접근 허용 범위)를 설정한다. Figma MCP 사용에는 아래 항목을 활성화한다.
| 스코프 | 설명 |
|---|---|
file_content:read | 피그마 파일 내용 읽기 권한 |
dev_resources:read | 개발 리소스(리소스: 자원) 읽기 권한 |
- Generate token(제너레이트 토큰) 버튼을 클릭한다.
1.1.7. 토큰 복사 및 보관
토큰이 생성되면 화면에 한 번만 표시된다. Copy this token(카피 디스 토큰) 버튼을 클릭해 복사한 뒤 안전한 곳에 보관한다.
주의
토큰은 생성 직후 화면에서만 확인할 수 있다. 창을 닫으면 다시 볼 수 없으므로 반드시 복사해 메모장 등에 저장해 두어야 한다.
1.1.8. Gemini CLI에서 토큰으로 Figma 인증
Gemini CLI 세션 안에서 아래 명령을 입력한다.
1/mcp auth figma| 코드 | 설명 |
|---|---|
/mcp auth | MCP 서버에 인증을 요청하는 명령 |
figma | 인증할 MCP 서버 이름 |
브라우저에 Figma OAuth(오어스: 오픈 인증) 화면이 열리면, 6.4에서 발급한 토큰을 붙여넣거나 Figma 계정으로 직접 로그인한 뒤 권한을 허용한다.
요약
인증 토큰은 ~/.gemini/mcp-oauth-tokens.json 파일에 저장되며, 만료 시 자동으로 갱신된다.
아래와 같은 메시지가 출력되면 인증이 완료된 것이다.
1✓ Successfully authenticated with figma MCP server1.2. 주요 도구
1.2.1. 읽기 도구 (Read)
디자인을 분석하고 정보를 추출하는 도구이다.
| 구분 | 명령어 | 설명 | 예시 프롬프트 |
|---|---|---|---|
| 디자인 추출 | get_design_context | 선택한 레이어의 구조, 스타일, 레이아웃을 코드로 변환 가능한 형태로 추출. 기본 출력은 React + Tailwind | Figma 선택 영역을 Vue로 생성해줘 |
| 변수 조회 | get_variable_defs | 디자인에 사용된 변수(Design Tokens) 조회. 색상, 간격, 타이포그래피 등 반환 | 선택 영역에 사용된 모든 디자인 토큰을 알려줘 |
| 스크린샷 | get_screenshot | 선택한 요소의 스크린샷 캡처. AI가 시각적 구조를 정확히 파악하도록 지원 | 이 프레임의 스크린샷을 찍어줘 |
| 메타데이터 | get_metadata | 레이어 ID, 이름, 타입, 위치, 크기 등 기본 속성을 XML 형식으로 반환 | 이 레이어의 메타데이터를 보여줘 |
| FigJam | get_figjam | FigJam 다이어그램의 메타데이터를 XML 형식으로 변환. 노드 속성과 스크린샷 포함 | FigJam 보드 내용을 분석해줘 |
| 코드 매핑 조회 | get_code_connect_map | Figma 노드 ID와 코드베이스 컴포넌트 간 매핑 정보 조회 | 이 컴포넌트의 코드 매핑을 확인해줘 |
| 코드 매핑 제안 | get_code_connect_suggestions | Figma 컴포넌트와 코드 컴포넌트 간 매핑을 자동 감지하고 제안 | 코드 매핑을 자동으로 찾아줘 |
1.2.2. 쓰기 도구 (Write)
디자인을 생성하거나 코드 매핑을 추가하는 도구이다.
| 구분 | 명령어 | 설명 | 예시 프롬프트 |
|---|---|---|---|
| 디자인 생성 | generate_figma_design | 웹 앱의 라이브 UI를 Figma 디자인 레이어로 변환. Remote 전용 | localhost:3000 화면을 Figma에 넣어줘 |
| 다이어그램 | generate_diagram | Mermaid 구문으로 FigJam 다이어그램 생성 (플로우차트, 간트, 시퀀스 등) | 사용자 로그인 흐름을 FigJam 다이어그램으로 만들어줘 |
| 코드 매핑 추가 | add_code_connect_map | Figma 노드 ID와 코드 컴포넌트 간 매핑을 수동으로 추가 | - |
| 규칙 생성 | create_design_system_rules | 디자인-코드 변환 시 AI에게 컨텍스트를 제공하는 규칙 파일 생성 | - |
| 매핑 전송 | send_code_connect_mappings | get_code_connect_suggestions로 감지된 매핑을 확인하고 전송 | - |
1.2.3. 지원 클라이언트
generate_figma_design 지원: Claude Code, Codex by OpenAI
| 클라이언트 | 데스크톱 서버 | 리모트 서버 |
|---|---|---|
| Cursor | O | O |
| VS Code | O | O |
| Claude Code | O | O |
| Codex by OpenAI | O | O |
| Gemini CLI | O | O |
| Kiro | O | O |
| Warp | O | O |
| Android Studio | O | O |
| Replit | - | O |
| Amazon Q | O | - |
| Openhands | O | - |
1.3. 주의사항
- 데스크톱 서버: Figma 앱에서 선택한 요소를 직접 프롬프트에 활용할 수 있다.
- 리모트 서버: 선택 기반 프롬프트가 불가능하며, 프레임/레이어 링크를 직접 전달해야 한다.
- Code Connect: (엔터프라이즈 플랜이상)설정하면 출력 품질이 크게 향상된다. 하나의 라이브러리에 여러 프레임워크 매핑이 가능하다.
1.5. 실전 프롬프트 예시
1.5.1. STEP 1: 디자인 분석
Figma MCP로 이 디자인을 분석해줘: [피그마 프레임 링크]레이아웃 구조, 색상(Hex), 폰트, 간격 정보를 정리해줘.1.5.2. STEP 2: HTML/CSS 코드 생성
분석한 디자인을 HTML/CSS로 변환해줘.- 시맨틱 HTML 태그 사용- CSS 변수로 디자인 토큰 정의- Flexbox 레이아웃- 모바일 우선(Mobile-first) 반응형1.5.3. STEP 3: 프레임워크 지정 생성
Figma 선택 영역을 React + Tailwind로 생성해줘.src/components/ui 폴더의 기존 컴포넌트를 재사용해.1.5.4. STEP 4: 디자인 토큰 추출
이 디자인에서 사용된 모든 디자인 토큰을 CSS 변수로 추출해줘.색상, 간격, 폰트 크기를 분류해서 정리해.1.5.5. STEP 5: 라이브 UI를 Figma로 전송
localhost:3000에서 실행 중인 앱 화면을 Figma 파일로 캡처해줘.1.5.6. STEP 6: 최적화 및 리팩토링
생성된 코드를 최적화해줘.- BEM 방법론으로 클래스명 정리- 주요 섹션마다 설명 주석 추가- 외부 라이브러리 없이 순수 CSS- 초보자가 이해할 수 있는 수준으로 작성