Figma MCP 서버 완전 가이드: 디자인에서 코드로의 브릿지

개요

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

MCP가 해결하는 문제

• 디자인-개발 간극 해소: 피그마 디자인을 직접 참조하여 정확한 구현
• 수동 전달 제거: 색상값, 간격, 폰트 등을 일일이 복사할 필요 없음
• 실시간 동기화: 디자인 변경 시 AI가 최신 정보 참조 가능
• 협업 강화: 댓글 읽기/쓰기로 디자이너-개발자 소통 지원

1. 사전 요구사항

필수 항목

Figma Access Token 발급 방법

1. Figma 설정 접속
2. Personal access tokens 섹션으로 이동
3. Generate new token 클릭
4. 토큰 이름 입력 (예: Claude MCP)
5. 권한 설정:
   • File content: Read-only (필수)
   • Comments: Read and write (선택)
6. Generate token 클릭
7. 생성된 토큰 복사 (한 번만 표시됨!)

⚠️ 주의: 토큰은 figd_로 시작합니다. 분실 시 재발급 필요.

2. Claude Desktop 앱 설정

설정 파일 위치

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

설정 방법

1. 설정 파일 열기:

# macOS
open ~/Library/Application\ Support/Claude/claude_desktop_config.json

# 파일이 없으면 생성
touch ~/Library/Application\ Support/Claude/claude_desktop_config.json

2. Figma MCP 설정 추가:

{
  "mcpServers": {
    "figma": {
      "command": "npx",
      "args": ["figma-mcp"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "figd_your_token_here"
      }
    }
  }
}

3. Claude Desktop 앱 재시작

여러 MCP 서버 함께 사용

{
  "mcpServers": {
    "figma": {
      "command": "npx",
      "args": ["figma-mcp"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "figd_xxx"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": [
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Projects/"
      ]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxx"
      }
    }
  }
}

3. Claude Code CLI 설정

방법 A: 명령어로 추가 (권장)

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

방법 B: 글로벌 설정 파일 편집

~/.claude.json 파일의 mcpServers 섹션에 추가:

{
  "mcpServers": {
    "figma": {
      "type": "stdio",
      "command": "npx",
      "args": ["figma-mcp"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "figd_xxx"
      }
    }
  }
}

방법 C: 프로젝트별 설정

프로젝트 루트에 .mcp.json 파일 생성:

{
  "mcpServers": {
    "figma": {
      "command": "npx",
      "args": ["figma-mcp"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "${FIGMA_ACCESS_TOKEN}"
      }
    }
  }
}

팁: 환경 변수 사용 시 .env 파일에 토큰 저장 후 .gitignore에 추가

설정 확인

# MCP 서버 목록 확인
claude mcp list

# 예상 출력:
# figma: npx figma-mcp - ✓ Connected

4. 원격 MCP 서버 (대안)

Figma에서 공식 제공하는 원격 MCP 서버도 있습니다. 로컬 설치 없이 클라우드에서 실행됩니다.

# 원격 서버 추가
claude mcp add --transport http figma https://mcp.figma.com/mcp

원격 서버 특징: - 별도 토큰 설정 불필요 (OAuth 인증 사용) - Claude Code 내에서 /mcp → 인증 진행 - Figma Desktop 앱 불필요

5. 실전: API 발급부터 파일 추가까지

Step 1: Figma Access Token 발급

1-1. Figma 설정 페이지 접속

https://www.figma.com/settings

1-2. Personal access tokens 섹션 찾기 - 페이지 아래로 스크롤 - "Personal access tokens" 섹션 확인

1-3. 토큰 생성

1. [Generate new token] 버튼 클릭
2. Token name: "Claude MCP" (또는 원하는 이름)
3. Expiration: "No expiration" 또는 기간 설정
4. Scopes 선택:
   ✓ File content (Read-only) - 필수
   ✓ Comments (Read and write) - 선택
5. [Generate token] 클릭
6. 생성된 토큰 복사 (figd_로 시작)

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

1-4. 토큰 저장 (권장 방법)

# 환경 변수로 저장 (~/.zshrc 또는 ~/.bashrc)
echo 'export FIGMA_ACCESS_TOKEN="figd_your_token_here"' >> ~/.zshrc
source ~/.zshrc

# 또는 프로젝트별 .env 파일
echo 'FIGMA_ACCESS_TOKEN=figd_your_token_here' > .env
echo '.env' >> .gitignore

Step 2: MCP 서버 설정

2-1. Claude Desktop 설정

# 설정 파일 열기
open ~/Library/Application\ Support/Claude/claude_desktop_config.json

2-2. Figma MCP 추가

{
  "mcpServers": {
    "figma": {
      "command": "npx",
      "args": ["figma-mcp"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "figd_your_token_here"
      }
    }
  }
}

2-3. Claude Desktop 재시작 - 완전히 종료 후 재실행 (Cmd+Q)

Step 3: Figma 파일 추가

3-1. Figma 파일 URL 가져오기

1. Figma에서 파일 열기
2. 상단 URL 복사
   예: https://www.figma.com/design/JFGurHe7UNMrJr3L3yXOln/DEV_KDA-공유용-?node-id=41-3

3-2. Claude에게 파일 추가 요청

이 Figma 파일을 분석해줘:
https://www.figma.com/design/JFGurHe7UNMrJr3L3yXOln/DEV_KDA-공유용-

3-3. 실제 실행 결과

⏺ figma - add_figma_file (url: "https://www.figma.com/design/...")
  ⎿ {
      "name": "DEV_KDA(공유용)",
      "key": "JFGurHe7UNMrJr3L3yXOln",
      ...
    }
  ⎿ Here is the thumbnail of the Figma file
  ⎿ [이미지 표시]
  ⎿ Here is the JSON representation of the Figma file

Step 4: 대용량 파일 처리 시 주의사항

발생 가능한 문제

문제 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"}}

원인: Figma 파일이 너무 커서 API 제한 초과

해결 방법

방법 1: 특정 노드만 조회

node-id를 사용해서 특정 프레임만 가져와줘:
https://www.figma.com/design/JFGurHe7UNMrJr3L3yXOln/...?node-id=41-3

또는:
figma:view_node를 사용해서 41-3 노드의 썸네일만 보여줘

방법 2: 페이지별로 분리

Figma 파일에서:
1. 각 페이지를 별도 파일로 복제
2. 작은 단위로 나눠서 분석 요청

방법 3: 로컬에서 구조 파악 후 요청

Figma에서 좌측 Layers 패널 구조를 복사해서:

파일 구조:
- Page 1: 메인 페이지
  - Header (41-3)
  - Hero Section (41-4)
  - Features (41-5)
- Page 2: 서브 페이지
  ...

이 구조에서 Header (41-3)만 HTML로 변환해줘

방법 4: 디자인 시스템만 추출

전체 파일 말고, 이 파일의 디자인 토큰만 추출해줘:
- Colors
- Typography
- Spacing
- Components 리스트

Step 5: HTML 작업 볼륨 산정

5-1. Figma에서 수동 확인

1. Layers 패널에서 전체 구조 확인
2. 페이지 수 / 프레임 수 카운트
3. 컴포넌트 복잡도 체크

5-2. Claude에게 구조 분석 요청

이 Figma 파일의 작업 볼륨을 산정하기 위해:

1. 전체 페이지/섹션 구조
2. 각 섹션별 컴포넌트 수
3. 컴포넌트 복잡도 (단순/중간/복잡)
4. 예상 HTML 작업 시간

위 정보를 정리해줘

5-3. 작업량 산정 기준

단순 컴포넌트 (30분):
- 버튼, 텍스트, 아이콘
- 단순 카드

중간 컴포넌트 (1-2시간):
- 폼 요소
- 네비게이션
- 카드 리스트

복잡한 컴포넌트 (3-5시간):
- 인터랙티브 요소
- 애니메이션
- 복잡한 레이아웃

실전 팁

대용량 파일 다루기

# 1. 먼저 파일 메타데이터만 확인
"이 Figma 파일의 기본 정보만 보여줘 (페이지 이름, 프레임 수)"

# 2. 특정 노드만 조회
"node-id 41-3의 상세 정보를 보여줘"

# 3. 단계별 접근
"첫 번째 페이지만 먼저 분석해줘"

효율적인 분석 요청

❌ 나쁜 예: "전체 파일 분석해줘"
✅ 좋은 예: "Header 섹션(41-3)의 HTML 구조와 스타일을 추출해줘"

❌ 나쁜 예: "다 만들어줘"
✅ 좋은 예: "버튼 컴포넌트부터 시작해서, 디자인 시스템 순으로 진행해줘"

6. Figma MCP 사용 방법

제공되는 도구(Tools)

실제 사용 예시

1. Figma 파일 분석 요청:

이 Figma 디자인을 분석해줘:
https://www.figma.com/file/ABC123/My-Design

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

2. 특정 컴포넌트 구현 요청:

이 Figma 프레임을 React 컴포넌트로 만들어줘:
https://www.figma.com/file/ABC123/My-Design?node-id=1:234

Tailwind CSS를 사용해줘.

3. 디자인 시스템 추출:

이 Figma 파일에서 디자인 토큰을 추출해서
CSS 변수로 만들어줘:
https://www.figma.com/file/ABC123/Design-System

6. 문제 해결

연결 확인

# Claude Code 내에서
/mcp

# 또는 터미널에서
claude mcp list

로그 확인

# macOS
tail -f ~/Library/Logs/Claude/mcp-server-figma.log

# 실시간 모니터링
tail -f ~/Library/Logs/Claude/mcp*.log | grep -i figma

일반적인 문제와 해결

문제 1: "Server disconnected" 오류

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

해결:

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

# npx 캐시 정리
npx clear-npx-cache

# 또는 figma-mcp 직접 설치
npm install -g figma-mcp

문제 2: "FIGMA_ACCESS_TOKEN" 오류

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

해결:

# 환경 변수 확인
echo $FIGMA_ACCESS_TOKEN

# 설정 파일에서 토큰 확인
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | grep FIGMA

문제 3: "Method not found" 경고

원인: MCP 프로토콜 버전 불일치 (무시해도 됨)

Message from server: {"error":{"code":-32601,"message":"Method not found"}}

이 경고는 resources/list 메서드를 지원하지 않아 발생하며, 기능에는 영향 없습니다.

문제 4: Node.js 버전 충돌 (nvm 사용 시)

원인: nvm 환경에서 잘못된 Node 버전 사용

해결:

# 현재 Node 버전 확인
nvm current

# 적절한 버전으로 변경
nvm use 18

# 해당 버전에서 figma-mcp 설치
npm install -g figma-mcp

완전 초기화 (최후의 수단)

# 기존 설정 제거
claude mcp remove figma

# npx 캐시 정리
rm -rf ~/.npm/_npx

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

# Claude Code 재시작

7. 보안 주의사항

API 토큰 관리

.gitignore 설정

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

환경 변수 사용 권장

# ~/.zshrc 또는 ~/.bashrc에 추가
export FIGMA_ACCESS_TOKEN="figd_xxx"

// .mcp.json에서 환경 변수 참조
{
  "mcpServers": {
    "figma": {
      "env": {
        "FIGMA_ACCESS_TOKEN": "${FIGMA_ACCESS_TOKEN}"
      }
    }
  }
}

8. 활용 팁

디자인-코드 워크플로우

1. 디자인 리뷰 단계

   이 Figma 파일의 컴포넌트 구조를 분석하고,
   React 컴포넌트 트리 구조를 제안해줘.
   

2. 스타일 추출 단계

   이 디자인에서 색상, 폰트, 간격 값을 추출해서
   Tailwind config 파일을 생성해줘.
   

3. 컴포넌트 구현 단계

   이 Button 컴포넌트(node-id: 1:234)를
   디자인과 동일하게 구현해줘.
   

4. 검증 단계

   구현한 코드가 Figma 디자인과 일치하는지 확인해줘.
   차이점이 있으면 알려줘.
   

효율적인 프롬프트

좋은 예:

이 Figma 프레임(https://figma.com/file/xxx?node-id=1:234)을
Next.js App Router 컴포넌트로 구현해줘.

요구사항:
- TypeScript 사용
- Tailwind CSS로 스타일링
- 반응형 지원 (모바일/데스크톱)
- 접근성 고려 (ARIA 라벨)

나쁜 예:

피그마 보고 코드 만들어줘

9. 대안: Figma Desktop MCP 서버

Figma Desktop 앱 내장 MCP 서버도 사용 가능합니다.

설정 방법

1. Figma Desktop 앱 실행
2. Dev Mode 활성화 (Shift+D)
3. Inspect 패널 → MCP server 섹션
4. Enable desktop MCP server 클릭
5. 서버 주소: http://127.0.0.1:3845/mcp

Claude Code에 추가

claude mcp add --transport http figma-desktop http://127.0.0.1:3845/mcp

비교

결론

Figma MCP 서버는 디자인-개발 워크플로우를 혁신적으로 개선합니다:

1. 설정 간단: 몇 줄의 설정으로 연동 완료
2. 실시간 접근: 최신 디자인을 AI가 직접 참조
3. 정확한 구현: 디자인 스펙을 그대로 코드로 변환
4. 협업 강화: 댓글을 통한 디자이너-개발자 소통

Claude Desktop과 Claude Code 모두에서 활용하여, 디자인 시안을 빠르고 정확하게 코드로 구현해보세요.

참고 자료

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