Windsurf Figma MCP 설정 — Cascade로 Figma 디자인 데이터 자동 활용하기
Windsurf IDE의 Cascade AI에 Figma MCP 서버를 연결해 디자인 데이터를 자동으로 코드에 반영하는 방법을 단계별로 설명합니다. 설치부터 실전 활용, 오류 해결까지 완전 가이드.
Windsurf IDE에 Figma MCP 서버를 연결하면, Cascade AI 에이전트가 Figma 디자인 파일에서 컴포넌트 구조·색상·타이포그래피 토큰을 직접 읽어 코드를 자동 생성합니다. 설계와 구현 사이의 반복적인 복사·붙여넣기 작업을 없앨 수 있으며, 설정은 JSON 파일 한 개와 Figma 토큰 발급으로 완료됩니다. 이 가이드는 처음 설정하는 분부터 오류를 겪는 분까지 전 과정을 단계별로 안내합니다.
Windsurf Figma MCP가 필요한 이유
디자이너가 Figma에서 확정한 UI를 개발자가 코드로 옮기는 과정에서, 색상 코드 하나·간격 값 하나를 실수로 다르게 입력하는 일은 흔합니다. 디자인 QA 라운드를 반복하고, 수정 요청이 쌓이며, 릴리스가 지연됩니다.
MCP(Model Context Protocol)는 Anthropic이 설계한 개방형 표준으로, AI 어시스턴트가 외부 도구·데이터 소스를 표준화된 방식으로 호출할 수 있게 해줍니다. Figma MCP 서버를 Windsurf에 연결하면 아래 흐름으로 디자인 데이터가 코드로 이어집니다.
개발자(Cascade 채팅)
│
▼
Windsurf Cascade AI
│ MCP 도구 호출
▼
Figma MCP 서버 (로컬 실행)
│ Figma REST API 요청
▼
Figma 파일 서버 (figma.com)
│ JSON 응답 (컴포넌트·토큰·레이어)
▼
Cascade → 코드(React/Vue/CSS 등) 자동 생성
Cascade가 자동으로 수행하는 작업
- Figma 파일 URL에서 컴포넌트 트리 파싱
- 디자인 토큰(색상, 타이포·간격) 추출 후 CSS 변수 또는 Tailwind 설정 생성
- 레이어 이름·속성을 기반으로 React/Vue 컴포넌트 뼈대 작성
- 반복 컴포넌트 감지 후 props 인터페이스 자동 제안
준비물
| 항목 | 최소 조건 | 확인 방법 |
|---|---|---|
| Windsurf IDE | 최신 버전 | windsurf.com에서 다운로드 |
| Node.js | 18 이상 | 터미널: node -v |
| Figma 계정 | 무료 플랜 이상 | figma.com |
| Figma Personal Access Token | 계정 설정에서 발급 | 아래 1단계 참고 |
단계별 설정 방법
1단계: Figma 개인 액세스 토큰 발급
Figma 웹사이트에 로그인한 뒤 아래 순서로 토큰을 발급합니다.
- 우측 상단 프로필 아이콘 클릭 → Settings 진입
- 좌측 메뉴에서 Security 탭 선택
- Personal access tokens 섹션에서 Generate new token 클릭
- 토큰 이름을 입력(예:
windsurf-mcp)하고 만료일을 설정한 후 Generate token 클릭 - 화면에 표시된 토큰을 복사해 안전한 곳에 보관 (이 화면을 벗어나면 다시 확인 불가)
2단계: Figma MCP 서버 설치
Figma가 공식 제공하는 MCP 서버 패키지를 설치합니다. 터미널을 열고 아래 명령을 실행합니다.
npm install -g @figma/mcp
설치가 완료되면 버전을 확인합니다.
figma-mcp --version
버전 번호가 출력되면 설치가 정상적으로 완료된 것입니다.
npm 글로벌 설치 대신 npx로 실행하고 싶다면 mcp_config.json에서 command를
npx로, args 첫 번째 요소를@figma/mcp로 지정해도 됩니다.
3단계: Windsurf MCP 설정 파일 작성
Windsurf의 MCP 서버 목록은 mcp_config.json 파일로 관리합니다.
설정 파일 경로
| 운영체제 | 경로 |
|---|---|
| macOS / Linux | ~/.codeium/windsurf/mcp_config.json |
| Windows | %USERPROFILE%\.codeium\windsurf\mcp_config.json |
해당 경로에 파일이 없으면 새로 생성합니다. 아래 내용을 입력하되, YOUR_FIGMA_TOKEN 부분을 1단계에서 복사한 토큰으로 교체하세요.
{
"mcpServers": {
"figma": {
"command": "figma-mcp",
"args": [],
"env": {
"FIGMA_ACCESS_TOKEN": "YOUR_FIGMA_TOKEN"
}
}
}
}
이미 다른 MCP 서버가 등록되어 있다면, 기존 mcpServers 객체 안에 "figma" 항목만 추가하면 됩니다.
4단계: Windsurf 재시작 및 Cascade 연결 확인
설정 파일을 저장한 뒤 Windsurf를 완전히 종료하고 다시 시작합니다.
- Windsurf 메뉴 → View → Cascade 패널을 엽니다.
- 채팅창 하단 또는 패널 상단에 MCP 도구 아이콘이 표시되는지 확인합니다.
- 도구 목록에
figma_*형태의 항목이 보이면 연결 성공입니다.
연결이 확인되지 않으면 아래 “흔한 오류와 해결 방법” 섹션을 참고하세요.
5단계: Figma 파일 URL로 디자인 데이터 불러오기
Cascade 채팅창에 Figma 파일 URL을 붙여넣고 원하는 정보를 요청합니다.
이 Figma 파일에서 디자인 토큰(색상, 폰트 크기, 간격)을 추출해줘:
https://www.figma.com/file/ABC123/MyDesign
Cascade가 MCP 도구를 통해 Figma API를 호출하고, 파일의 스타일·컴포넌트 정보를 JSON 형태로 받아 요약해 줍니다.
6단계: 디자인 토큰 기반 코드 자동 생성
추출된 데이터를 바탕으로 실제 코드를 요청합니다.
방금 추출한 색상 토큰으로 Tailwind CSS 설정 파일을 작성해줘.
그리고 Button 컴포넌트를 React + TypeScript로 구현해줘.
Cascade는 Figma에서 읽어온 실제 값을 사용하므로, 색상 코드·폰트 크기 등이 디자인과 정확히 일치하는 코드를 생성합니다.
흔한 오류와 해결 방법
| 오류 상황 | 원인 | 해결 방법 |
|---|---|---|
| Cascade에 MCP 도구가 표시되지 않음 | 설정 파일 경로 오류 또는 JSON 문법 오류 | 파일 경로를 재확인하고, JSON 검증 도구로 문법 점검 후 Windsurf 재시작 |
figma-mcp: command not found | npm 글로벌 설치 실패 또는 PATH 미등록 | npm list -g @figma/mcp로 설치 확인, npx 방식으로 전환 고려 |
| ”Unauthorized” 또는 401 오류 | Figma 토큰 만료 또는 입력 오류 | Figma Settings에서 새 토큰 발급 후 mcp_config.json 갱신 |
| 파일을 찾을 수 없다는 오류 | 비공개 파일이거나 URL 형식 오류 | Figma 파일에 뷰어 권한이 있는지 확인, URL에서 /file/ 경로 확인 |
| 응답이 느리거나 타임아웃 | 대용량 Figma 파일 | 특정 페이지나 컴포넌트만 지정해서 요청 |
실전 활용 패턴
Figma MCP와 Cascade를 함께 활용할 때 효과적인 프롬프트 패턴을 정리합니다.
디자인 토큰 추출 후 CSS 변수 생성
이 Figma 파일의 스타일(색상·폰트·간격)을 CSS 커스텀 프로퍼티로 변환해줘:
https://www.figma.com/file/XYZ789/DesignSystem
컴포넌트 구조 분석 후 코드 스캐폴딩
Figma의 "Card" 컴포넌트 구조를 분석해서
React 컴포넌트와 TypeScript 인터페이스를 만들어줘.
디자인-코드 일치 검증
현재 Button.tsx 파일의 색상 값이
Figma 디자인 시스템과 일치하는지 비교해줘.
다음 단계
Windsurf Figma MCP 설정이 완료됐다면, 작업 환경을 더 확장해볼 수 있습니다.
- 코르독(KorDoc) MCP: HWP·PDF·XLSX 등 공문서를 Markdown으로 변환해 AI에 제공하는 서버. 디자인 가이드 문서를 AI에 바로 연결할 때 유용합니다.
- HWP-MCP (한글 문서 MCP 서버): 한글(.hwp) 파일을 AI가 직접 읽고 편집할 수 있게 해주는 서버로, 기획 문서와 디자인 작업을 함께 자동화할 수 있습니다.
- 한포지(HwpForge) MCP: HWPX 문서를 AI 에이전트가 읽고 변환하는 서버. 디자인 스펙이 한글 파일로 전달되는 환경에서 활용도가 높습니다.
- 개발 도구 카테고리: Windsurf·Cursor 등 AI IDE와 연동 가능한 MCP 서버 전체 목록을 확인할 수 있습니다.
- 전체 서버 목록: MCP모아에 등록된 모든 MCP 서버를 카테고리별로 탐색합니다.
직접 개발한 Figma 관련 MCP 서버가 있다면 MCP모아에 등록해 더 많은 개발자와 공유해 보세요.
자주 묻는 질문
Windsurf에서 Figma MCP를 사용하려면 Figma 유료 플랜이 필요한가요?
아닙니다. Figma Personal Access Token은 무료 Figma 계정에서도 발급할 수 있습니다. 다만 팀 라이브러리나 비공개 파일에 접근하려면 해당 파일에 대한 뷰어 이상의 권한이 있어야 합니다.
Windsurf MCP 설정 파일의 위치는 어디인가요?
macOS 기준으로 ~/.codeium/windsurf/mcp_config.json 파일에 MCP 서버를 등록합니다. Windows는 %USERPROFILE%\.codeium\windsurf\mcp_config.json 경로입니다. 파일이 없으면 직접 생성해야 합니다.
Cascade가 Figma 도구를 인식하지 못할 때 어떻게 하나요?
Windsurf를 완전히 종료 후 재시작하고, mcp_config.json의 JSON 문법(쉼표, 따옴표)을 다시 확인하세요. 터미널에서 Node.js 버전(node -v)이 18 이상인지도 확인하세요.
Figma MCP로 어떤 정보를 추출할 수 있나요?
Figma 파일의 컴포넌트 구조, 색상·타이포그래피·간격 디자인 토큰, 레이어 이름과 속성, 텍스트 콘텐츠 등을 추출할 수 있습니다. 이를 바탕으로 Cascade가 CSS 변수, React 컴포넌트, Tailwind 클래스 등을 자동 생성할 수 있습니다.
Windsurf와 Cursor 중 Figma MCP 지원이 더 나은 쪽은 어디인가요?
두 IDE 모두 MCP 표준을 지원하므로 동일한 Figma MCP 서버를 사용할 수 있습니다. Windsurf는 Cascade라는 내장 AI 에이전트를 통해 맥락을 유지하면서 연속 대화로 디자인을 코드화하는 흐름이 자연스럽습니다.
Figma MCP 서버의 공식 저장소는 어디서 확인할 수 있나요?
Figma가 공식 제공하는 MCP 서버는 github.com/figma/figma-developer-mcp 에서 확인할 수 있습니다. README의 설치 지침을 참고해 최신 버전을 사용하세요.