본문 바로가기
M MCP모아
튜토리얼

Windsurf Figma MCP 설정 — Cascade로 Figma 디자인 데이터 자동 활용하기

Windsurf IDE의 Cascade AI에 Figma MCP 서버를 연결해 디자인 데이터를 자동으로 코드에 반영하는 방법을 단계별로 설명합니다. 설치부터 실전 활용, 오류 해결까지 완전 가이드.

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.js18 이상터미널: node -v
Figma 계정무료 플랜 이상figma.com
Figma Personal Access Token계정 설정에서 발급아래 1단계 참고

단계별 설정 방법

1단계: Figma 개인 액세스 토큰 발급

Figma 웹사이트에 로그인한 뒤 아래 순서로 토큰을 발급합니다.

  1. 우측 상단 프로필 아이콘 클릭 → Settings 진입
  2. 좌측 메뉴에서 Security 탭 선택
  3. Personal access tokens 섹션에서 Generate new token 클릭
  4. 토큰 이름을 입력(예: windsurf-mcp)하고 만료일을 설정한 후 Generate token 클릭
  5. 화면에 표시된 토큰을 복사해 안전한 곳에 보관 (이 화면을 벗어나면 다시 확인 불가)

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를 완전히 종료하고 다시 시작합니다.

  1. Windsurf 메뉴 → View → Cascade 패널을 엽니다.
  2. 채팅창 하단 또는 패널 상단에 MCP 도구 아이콘이 표시되는지 확인합니다.
  3. 도구 목록에 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 foundnpm 글로벌 설치 실패 또는 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의 설치 지침을 참고해 최신 버전을 사용하세요.

이 글과 관련된 MCP 서버