Figma MCP 완전 정복: 설치부터 실전 활용까지

개요

Figma MCP (Model Context Protocol) 서버는 AI 코딩 도구(Claude Desktop, Claude Code)가 Figma 디자인 파일에 직접 접근할 수 있게 해주는 연결 도구입니다. 디자이너가 만든 디자인을 AI가 읽고, 이를 바탕으로 정확한 코드를 생성할 수 있습니다.

MCP가 해결하는 문제

1. MCP 서버 유형 비교

Figma MCP를 사용하는 방법은 3가지가 있습니다:

권장 조합

figma-mcp + figma-desktop 동시 사용을 권장합니다: - figma-mcp: 파일 추가, 댓글 읽기/쓰기 - figma-desktop: 빠른 디자인 컨텍스트 조회, 스크린샷

# 현재 설정 확인
claude mcp list

# 예상 출력:
# figma: npx figma-mcp - ✓ Connected
# figma-desktop: http://127.0.0.1:3845/mcp (HTTP) - ✓ Connected

2. figma-mcp 설치 (API 토큰 방식)

2.1 Figma Access Token 발급

1. Figma 설정 접속
2. Personal access tokens 섹션으로 이동
3. Generate new token 클릭
4. 설정:
   • Token name: Claude MCP (원하는 이름)
   • Expiration: No expiration 또는 기간 설정
   • Scopes:
     • ✅ File content (Read-only) - 필수
     • ✅ Comments (Read and write) - 선택
5. Generate token 클릭
6. 생성된 토큰 복사 (figd_로 시작)

⚠️ 중요: 토큰은 생성 직후 한 번만 표시됩니다. 안전한 곳에 저장하세요!

2.2 환경 변수로 토큰 저장 (권장)

# ~/.zshrc 또는 ~/.bashrc에 추가
echo 'export FIGMA_ACCESS_TOKEN="figd_your_token_here"' >> ~/.zshrc
source ~/.zshrc

2.3 Claude Code에 MCP 추가

# figma-mcp 추가
claude mcp add figma -e FIGMA_ACCESS_TOKEN=figd_xxx -- npx figma-mcp

또는 환경 변수 사용 시:

claude mcp add figma -e FIGMA_ACCESS_TOKEN=$FIGMA_ACCESS_TOKEN -- npx figma-mcp

2.4 연결 확인

claude mcp list
# figma: npx figma-mcp - ✓ Connected

3. figma-desktop 설치 (Desktop 앱 방식)

Figma Desktop 앱에 내장된 MCP 서버를 사용하는 방법입니다. 별도의 토큰 없이 Figma 앱 로그인만으로 인증됩니다.

3.1 사전 요구사항

• Figma Desktop 앱 설치 (웹 버전 아님)
• Figma 계정 로그인 상태

3.2 MCP 서버 활성화

1. Figma Desktop 앱 실행
2. Dev Mode 활성화: Shift + D 또는 우측 상단 토글
3. Inspect 패널 열기 (우측 사이드바)
4. MCP server 섹션 찾기
5. Enable desktop MCP server 클릭

3.3 Claude Code에 추가

# HTTP 전송 방식으로 추가
claude mcp add --transport http figma-desktop http://127.0.0.1:3845/mcp

3.4 연결 확인

claude mcp list
# figma-desktop: http://127.0.0.1:3845/mcp (HTTP) - ✓ Connected

3.5 figma-desktop의 장점

3.6 figma-desktop 전용 도구

4. 실전 활용법

4.1 Figma 파일 분석하기

기본 요청:

이 Figma 파일을 분석해줘:
https://www.figma.com/design/ABC123/My-Design

상세 요청 (권장):

이 Figma 디자인의 Header 섹션(node-id: 41-3)을 분석해줘:
https://www.figma.com/design/ABC123/My-Design?node-id=41-3

분석 내용:
- 사용된 색상 팔레트
- 컴포넌트 구조
- 반응형 브레이크포인트

4.2 node-id 활용하기

Figma URL에서 node-id를 추출하는 방법:

URL: https://www.figma.com/design/ABC123/Design?node-id=41-3
                                                       ^^^^
                                                    이 부분이 node-id

Claude에서 사용 시: "41-3" 또는 "41:3" 형태 모두 가능

특정 노드만 조회:

node-id 41-3의 디자인 정보를 가져와줘

4.3 컴포넌트 → 코드 변환

HTML/CSS 변환:

이 Figma 프레임(node-id: 41-3)을 HTML로 구현해줘:

요구사항:
- Tailwind CSS 사용
- 반응형 지원 (모바일/데스크톱)
- 시맨틱 HTML 구조

React 컴포넌트:

이 버튼 컴포넌트(node-id: 52-10)를 React + TypeScript로 만들어줘:

요구사항:
- Tailwind CSS 스타일링
- 호버/포커스 상태 구현
- 접근성 고려 (ARIA)

4.4 디자인 토큰 추출

이 Figma 파일에서 디자인 시스템 토큰을 추출해줘:

필요한 정보:
- Colors (primary, secondary, gray scale)
- Typography (font family, sizes, weights)
- Spacing (padding, margin 기준)
- Border radius
- Shadow

출력 형식: CSS 변수 또는 Tailwind config

4.5 디자인 비교 및 검증

현재 구현된 코드와 Figma 디자인(node-id: 41-3)을 비교해줘:

확인 사항:
- 색상 일치 여부
- 간격/여백 정확도
- 폰트 스타일 일치
- 누락된 요소

5. 대용량 파일 처리

5.1 발생 가능한 문제

⚠ Large MCP response (~8.1m tokens), this can fill up context quickly
API Error: 413 {"error":{"type":"request_too_large","message":"Request exceeds the maximum size"}}

5.2 해결 방법

방법 1: 특정 노드만 조회

전체 파일 대신 Header(41-3)만 분석해줘

방법 2: 메타데이터 먼저 확인

이 파일의 페이지 구조와 프레임 목록만 보여줘

방법 3: 단계별 접근

1단계: 페이지 1의 구조 파악
2단계: 각 섹션별 상세 분석
3단계: 필요한 컴포넌트만 코드 변환

방법 4: figma-desktop의 get_screenshot 활용

이 노드의 스크린샷을 보여주고, 이미지 기반으로 분석해줘

6. 효율적인 프롬프트 작성

좋은 예 vs 나쁜 예

컨텍스트 제공 팁

이 프로젝트의 기술 스택:
- Next.js 14 (App Router)
- TypeScript
- Tailwind CSS
- Rhymix CMS 연동

이 Figma 프레임(41-3)을 위 스택에 맞게 구현해줘.

7. 문제 해결

7.1 연결 확인

# MCP 서버 상태 확인
claude mcp list

# figma-desktop 연결 테스트
curl http://127.0.0.1:3845/mcp 2>/dev/null && echo "Connected" || echo "Not connected"

7.2 일반적인 문제와 해결

"Server disconnected" 오류

원인: 서버가 예기치 않게 종료됨

해결:

# Node.js 버전 확인 (v16 이상 필요)
node --version

# npx 캐시 정리 후 재시도
npx clear-npx-cache
claude mcp remove figma
claude mcp add figma -e FIGMA_ACCESS_TOKEN=figd_xxx -- npx figma-mcp

figma-desktop 연결 실패

원인: Figma Desktop 앱이 실행 중이지 않거나 MCP 서버가 비활성화됨

해결: 1. Figma Desktop 앱 실행 확인 2. Dev Mode 활성화 (Shift+D) 3. MCP server 토글 확인 4. 앱 재시작

"FIGMA_ACCESS_TOKEN" 오류

원인: 토큰이 없거나 잘못됨

해결:

# 환경 변수 확인
echo $FIGMA_ACCESS_TOKEN

# 토큰 재설정
claude mcp remove figma
claude mcp add figma -e FIGMA_ACCESS_TOKEN=figd_new_token -- npx figma-mcp

7.3 로그 확인

# macOS Claude 로그
tail -f ~/Library/Logs/Claude/mcp*.log | grep -i figma

8. 보안 권장사항

API 토큰 관리

.gitignore 설정

# MCP 설정 파일 (토큰 포함 시)
.mcp.json
.env
.env.local

# Claude 설정
.claude.json

figma-desktop 사용 시 장점

figma-desktop은 토큰 관리가 불필요하므로: - 토큰 유출 위험 없음 - 팀원별 개인 Figma 계정으로 인증 - 권한은 Figma 팀 설정에 따름

9. 워크플로우 예시

신규 컴포넌트 구현 워크플로우

1. 디자인 파일 분석
   "이 Figma 파일의 컴포넌트 구조를 분석해줘"

2. 디자인 토큰 추출
   "사용된 색상과 폰트를 CSS 변수로 만들어줘"

3. 기본 컴포넌트부터 구현
   "Button 컴포넌트(52-10)를 먼저 구현해줘"

4. 복합 컴포넌트 구현
   "Card 컴포넌트(52-20)를 Button을 활용해서 구현해줘"

5. 디자인 검증
   "구현된 코드가 Figma와 일치하는지 확인해줘"

참고 자료

• Figma MCP Server npm
• Figma MCP 공식 가이드
• Model Context Protocol 문서
• Claude Code MCP 설정

요약

핵심: figma-mcp와 figma-desktop을 함께 사용하면 각각의 장점을 모두 활용할 수 있습니다.