목차
- 디자인 시안 코드로 옮기다가 지쳤다
- Claude Figma MCP 서버가 하는 일
- get_design_context — 디자인에서 코드 뽑아내기
- Code Connect — 이게 없으면 반쪽짜리다
- Figma로 디자인 역방향 쓰기
- MCP 도구별 용도 정리
- 실무에서 쓸 때 주의할 점
- 워크플로우 요약 — 세 단계면 끝난다
디자인 시안 코드로 옮기다가 지쳤다
Figma에서 Dev Mode 열어놓고 CSS 속성 하나씩 복사해서 붙여넣는 작업을 하고 있었다. 컴포넌트 하나에 padding, border-radius, font-size, color 값을 일일이 옮기는데 카드 UI 10개를 변환하는 데만 두 시간 가까이 걸렸다. 디자이너가 시안을 수정할 때마다 이 과정을 반복해야 한다는 게 문제였다. Figma 플러그인 몇 개를 써봤지만 프로젝트에서 쓰는 컴포넌트 구조와 맞지 않아서 결국 수작업으로 돌아왔다.
그러다 Claude의 Figma MCP 연동을 알게 됐다. Anthropic이 공식으로 제공하는 Figma MCP 서버인데, 단순히 디자인을 "읽는" 수준이 아니라 Code Connect를 통해 프로젝트의 기존 컴포넌트에 자동 매핑까지 해준다. 심지어 Figma 쪽으로 디자인을 다시 써넣는 것도 가능하다. 연동하고 나서 체감상 디자인→코드 전환 시간이 절반 이하로 줄었다.
Claude Figma MCP 서버가 하는 일
MCP(Model Context Protocol)는 Claude가 외부 도구와 통신하는 프로토콜이다. Figma MCP 서버는 Anthropic이 공식 제공하는 서버로, Claude가 Figma 파일을 직접 읽고 쓸 수 있게 해준다. (출처: Anthropic MCP 공식 문서, 2026년 4월 기준)
핵심 도구는 크게 세 범주로 나뉜다.
읽기 도구 — get_design_context, get_screenshot, get_metadata, get_figjam. Figma 파일에서 디자인 정보를 가져온다. get_design_context가 메인이고, React + Tailwind 기반 코드와 스크린샷, 컨텍스트 힌트를 한 번에 돌려준다.
쓰기 도구 — create_new_file, generate_diagram. Figma에 새 파일을 만들거나 FigJam에 다이어그램을 생성한다. 코드에서 디자인으로 역방향 전환이 가능한 부분이다.
매핑 도구 — get_code_connect_map, add_code_connect_map, send_code_connect_mappings. Figma 컴포넌트와 코드베이스 컴포넌트 간 매핑을 관리한다. 이게 없으면 매번 변환 결과를 수동으로 프로젝트에 맞춰야 한다.
get_design_context — 디자인에서 코드 뽑아내기
이 도구가 전체 워크플로우의 출발점이다. Figma URL에서 fileKey와 nodeId를 추출해서 호출하면, 해당 노드의 디자인 정보를 코드로 변환해서 돌려준다.
URL 파싱 규칙
Figma URL 구조를 먼저 이해해야 한다. URL 형태에 따라 fileKey와 nodeId 추출 방식이 다르다.
# 일반 디자인 파일
figma.com/design/:fileKey/:fileName?node-id=:nodeId
# nodeId의 "-"를 ":"로 변환해야 한다
# 브랜치 파일 — fileKey 대신 branchKey를 쓴다
figma.com/design/:fileKey/branch/:branchKey/:fileName
# Make 파일
figma.com/make/:makeFileKey/:makeFileName
# FigJam 보드 — get_figjam을 써야 한다
figma.com/board/:fileKey/:fileName
브랜치 파일에서 fileKey 대신 branchKey를 써야 한다는 걸 모르고 한참 헤맸다. get_design_context가 빈 결과를 돌려주길래 URL을 세 번쯤 다시 확인하고 나서야 브랜치 구조 때문이라는 걸 알았다.
반환 데이터 구조
get_design_context는 단순 CSS 덤프가 아니다. 반환값에는 여러 층위의 정보가 포함된다.
// get_design_context 반환 예시 (개념적 구조)
{
code: "...", // React + Tailwind 코드
screenshot: "...", // 디자인 스크린샷
hints: {
codeConnect: [...], // Code Connect로 매핑된 컴포넌트 스니펫
documentation: [...], // 컴포넌트 문서 링크
annotations: [...], // 디자이너가 남긴 노트
tokens: [...] // 디자인 토큰 (CSS 변수)
}
}
여기서 hints가 핵심이다. Code Connect 스니펫이 있으면 변환된 코드 대신 프로젝트에 이미 있는 컴포넌트를 바로 쓸 수 있다. 문서 링크가 있으면 해당 컴포넌트의 사용 가이드라인을 참고할 수 있고, 디자이너 어노테이션이 있으면 디자인 의도를 놓치지 않는다.
반환되는 코드는 React + Tailwind 기반이다. 프로젝트가 Vue나 Svelte를 쓴다면 이걸 그대로 붙여넣으면 안 된다. 참고 자료로 활용하고, 프로젝트 스택에 맞게 변환해야 한다. raw hex 색상이나 절대 좌표가 나오는 경우도 있는데, 이건 Figma 쪽에서 디자인 토큰이 제대로 설정되지 않았다는 신호다.
Code Connect — 이게 없으면 반쪽짜리다
get_design_context만 쓰면 매번 생성된 코드를 프로젝트 컴포넌트에 수동으로 맞춰야 한다. Button 컴포넌트가 프로젝트에 이미 있는데, 변환 결과가 인라인 스타일로 된 <button>을 뱉으면 의미가 없다.
Code Connect는 Figma 컴포넌트와 코드베이스 컴포넌트 간 매핑 테이블이다. 한 번 설정해두면 get_design_context 호출 시 매핑된 컴포넌트 스니펫을 자동으로 돌려준다.
매핑 설정 과정
// Code Connect 매핑 예시
// Figma의 "Primary Button" 컴포넌트를 프로젝트의 Button에 연결
{
figmaComponent: "Primary Button",
codeComponent: "@/components/ui/Button",
propMapping: {
"Label": "children", // Figma 텍스트 → children prop
"Size": "size", // Figma variant → size prop
"Disabled": "disabled" // Figma boolean → disabled prop
}
}
get_code_connect_suggestions를 먼저 호출하면 Claude가 Figma 컴포넌트와 코드베이스를 분석해서 매핑 후보를 제안해준다. 처음 설정할 때 이걸로 시작하면 시간을 많이 아낀다.
카드 컴포넌트 매핑할 때 경험인데, Figma에서 "Card/Default", "Card/With Image", "Card/Compact" 같은 variant가 있었다. 이걸 프로젝트의 <Card variant="default|image|compact"> 하나로 매핑하니까 이후부터 시안에 카드가 들어간 페이지는 거의 자동으로 코드가 나왔다. prop 매핑을 한 번 제대로 잡아두면 변환 정확도가 확 올라간다.
매핑이 잘못됐을 때
add_code_connect_map으로 매핑을 추가하거나 수정할 수 있다. send_code_connect_mappings는 매핑 정보를 Figma 쪽에 동기화하는 도구다. 팀에서 같이 쓰려면 이걸 반드시 실행해야 한다. 개인 로컬에서만 매핑을 갖고 있으면 다른 팀원은 혜택을 못 받는다.
Figma로 디자인 역방향 쓰기
create_new_file로 Figma에 새 파일을 만들 수 있고, generate_diagram으로 FigJam에 다이어그램을 생성할 수 있다. 아직 직접 많이 써보지 않아서 정확한 한계는 모르겠다. 다만 아키텍처 다이어그램이나 플로우차트를 FigJam에 바로 그려넣는 용도로는 괜찮았다. 코드에서 복잡한 UI를 Figma로 역변환하는 건 기대하지 않는 게 좋다. 현재 기준으로는 간단한 레이아웃이나 다이어그램 수준이다.
MCP 도구별 용도 정리
어떤 상황에서 어떤 도구를 써야 하는지 자주 헷갈려서 정리해봤다.
| 상황 | 사용 도구 | 비고 |
|---|---|---|
| Figma 시안을 코드로 변환 | get_design_context |
fileKey + nodeId 필요. 메인 도구 |
| 디자인 스크린샷만 필요 | get_screenshot |
코드 없이 이미지만 반환 |
| FigJam 보드 내용 읽기 | get_figjam |
board URL일 때만 사용 |
| 컴포넌트 매핑 제안받기 | get_code_connect_suggestions |
초기 설정 시 유용 |
| 매핑 추가/수정 | add_code_connect_map |
prop 단위로 설정 |
| 팀에 매핑 공유 | send_code_connect_mappings |
Figma 쪽에 동기화 |
| FigJam에 다이어그램 생성 | generate_diagram |
아키텍처, 플로우 용도 |
| Figma에 새 파일 생성 | create_new_file |
역방향 디자인 생성 |
| 디자인 토큰 조회 | get_variable_defs |
CSS 변수 매핑에 활용 |
실무에서 쓸 때 주의할 점
반환 코드를 그대로 쓰지 마라
get_design_context가 돌려주는 코드는 React + Tailwind 기반이다. 프로젝트 스택이 다르면 참고만 해야 한다. Vue 프로젝트에 React JSX를 붙여넣는 실수를 하는 사람은 없겠지만, 같은 React 프로젝트라도 상태 관리 방식, 라우팅 구조, 스타일링 컨벤션이 다르다. Code Connect 매핑을 설정하지 않은 상태에서 나온 코드는 프로토타이핑용으로만 쓰는 게 맞다.
디자인 토큰이 없으면 결과가 나빠진다
Figma 쪽에서 디자인 토큰(색상, 타이포그래피, 스페이싱)을 변수로 관리하지 않으면 get_design_context 결과에 raw hex 값과 절대 픽셀 값이 나온다. get_variable_defs로 토큰을 조회해서 프로젝트의 CSS 변수에 매핑하는 과정이 필요하다. 토큰 체계가 잘 잡혀 있는 디자인 시스템이면 변환 품질이 확연히 다르다.
브랜치 파일 URL 주의
Figma 브랜치 기능을 쓰는 팀이라면 URL에서 fileKey 대신 branchKey를 추출해야 한다. URL 구조가 figma.com/design/:fileKey/branch/:branchKey/:fileName일 때, API에 넘겨야 하는 건 branchKey다. 이걸 모르면 빈 결과가 나오거나 메인 브랜치의 오래된 디자인을 가져오게 된다.
nodeId 하이픈 변환
URL의 node-id 파라미터에 있는 하이픈(-)을 콜론(:)으로 변환해야 한다. node-id=123-456이면 API에는 123:456으로 넘겨야 한다. 이것도 처음에 몰라서 에러를 만난 부분이다. 공식 문서에 나와 있긴 한데 놓치기 쉽다.
# nodeId 변환 — 단순하지만 빠뜨리면 에러난다
def parse_figma_node_id(url_node_id: str) -> str:
"""URL의 node-id 파라미터를 API용 포맷으로 변환"""
return url_node_id.replace("-", ":")
# 사용 예시
node_id = parse_figma_node_id("123-456") # "123:456"
워크플로우 요약 — 세 단계면 끝난다
전체 흐름을 단계별로 정리하면 이렇다.
1단계: Code Connect 매핑 설정 (최초 1회)
└─ get_code_connect_suggestions → 제안 확인 → add_code_connect_map
└─ send_code_connect_mappings (팀 공유)
2단계: 디자인 → 코드 변환 (매 작업마다)
└─ Figma URL에서 fileKey, nodeId 추출
└─ get_design_context 호출
└─ hints 확인 → Code Connect 매핑 있으면 기존 컴포넌트 사용
└─ 없으면 생성된 코드를 프로젝트에 맞게 수정
3단계: 디자인 토큰 동기화 (필요 시)
└─ get_variable_defs → 프로젝트 CSS 변수에 매핑
핵심은 1단계를 얼마나 꼼꼼하게 하느냐다. Code Connect 매핑이 잘 잡혀 있으면 2단계에서 수동 작업이 거의 없어진다. 매핑 없이 get_design_context만 쓰면 결국 복사-붙여넣기-수정의 반복이라 자동화 효과가 크지 않다.
Figma MCP 서버 설정은 Anthropic 공식 MCP 저장소(github.com/anthropics/anthropic-tools, 2026년 4월 기준)에서 확인할 수 있다. Claude Desktop이나 Claude Code에서 MCP 서버 설정에 Figma 서버를 추가하면 바로 쓸 수 있다.
개인적으로는 디자인 시스템이 어느 정도 갖춰진 팀에서 이 워크플로우의 효과가 가장 크다고 느꼈다. 디자인 토큰도 없고 컴포넌트 체계도 없는 상태에서 쓰면 그냥 Figma Dev Mode 복사하는 것과 큰 차이가 없다. Code Connect 매핑부터 세팅하는 게 첫 번째 할 일이다.
관련 글
- Claude API Python 연동 가이드 — 첫 호출부터 챗봇 구현까지 – Claude API를 Python에서 처음 연동하면서 겪은 시행착오를 기록했다. .env 파일의 따옴표 하나로 45분을 소모한 인증 에러,…
- Claude MCP 서버 직접 만들기 — AI 에이전트 MCP 연동 실무 가이드 – Claude MCP 서버를 직접 만들면서 겪은 삽질을 TIL로 정리했다. stdio transport에서 막힌 이유, Python SDK …
- Gemini vs Claude vs ChatGPT — 2026년 AI 모델 비교 실전 테스트 – Gemini 2.5 Pro, Claude 4 Sonnet, GPT-4.5를 동일 조건에서 테스트했다. 코드 생성, 한국어 요약, API 비…
