← 목록으로AI WORKFLOW

Figma MCP 무료 연동 — Claude Code와 Codex에 디자인 붙이기

seungjin14 min2026-08-22
Figma MCP 무료 연동 — Claude Code와 Codex에 디자인 붙이기

Figma 시안을 코드로 옮기는 작업은 여전히 눈으로 보고 손으로 옮기는 일입니다. MCP가 나오면서 LLM이 Figma 파일을 직접 읽을 수 있게 됐는데, 막상 공식 문서대로 붙여 보면 무료 플랜에서는 거의 못 씁니다.

핵심부터 말하면 이렇습니다. Figma 공식 MCP 서버는 Starter(무료) 플랜에서 월 20회 툴 호출로 제한됩니다. 유료 플랜이라도 View나 Collab 시트면 월 6회까지 더 줄어듭니다. 프레임 몇 개 읽고 이미지 몇 장 받으면 그달치가 끝나는 양이라, 무료로 계속 쓰려면 다른 경로가 필요합니다.

Figma 공식 문서의 MCP 서버 요금제별 툴 호출 한도 표 — Starter는 월 20회, 유료 플랜의 View/Collab 시트는 월 6회, Dev/Full 시트는 하루 200~600회

Figma 개발자 문서에 시트와 플랜별 한도가 표로 정리돼 있습니다. Dev나 Full 시트를 받는 순간 하루 200회로 뛰기 때문에, 결국 시트 종류가 갈림길입니다.

세 가지 경로 비교

공식 Figma MCP Framelink Talk to Figma
방식 원격/로컬 MCP 서버 REST API 래핑 플러그인 ↔ WebSocket
인증 OAuth / 데스크톱 앱 개인 액세스 토큰(PAT) 토큰 없음 (플러그인이 담당)
무료 플랜 월 20회 툴 호출 REST API 한도 내 자유 제한 없음
방향 읽기 읽기 읽기 + 쓰기
데이터 Dev Mode 컨텍스트, 코드 커넥트 파일 레이아웃·스타일 JSON 선택한 노드 직접 조작
리스크 없음 토큰이 워크스페이스 전체 파일에 접근 로컬 서버·플러그인을 계속 띄워둬야 함

공식 서버는 Dev Mode를 그대로 끌어오기 때문에 품질이 확실히 좋습니다. 원격 서버(mcp.figma.com) 자체는 모든 플랜에서 붙일 수 있지만 한도 때문에 Dev 또는 Full 시트가 있어야 제 성능이 납니다. 데스크톱 앱 로컬 서버는 아예 유료 플랜의 Dev/Full 시트 전용입니다. Framelink는 Figma REST API를 감싸서 레이아웃과 스타일을 JSON으로 정리해 주는 서드파티 서버고 무료 계정 토큰만 있으면 됩니다.

세 번째 Talk to Figma는 성격이 다릅니다. 앞의 둘이 Figma를 읽어오는 도구라면 이건 에이전트가 Figma를 조작하는 통로예요. 시안을 코드로 옮기는 게 목적이면 앞의 둘, 텍스트 일괄 교체나 컴포넌트 오버라이드 전파처럼 디자인 작업 자체를 시키고 싶으면 세 번째입니다.

무료로 시작한다면 Framelink부터 붙이고, 팀이 유료 플랜으로 올라가면 공식 서버로 갈아타는 순서를 권합니다.

1. Figma 개인 액세스 토큰 발급

Framelink 경로는 토큰이 전부입니다.

  1. Figma 홈 좌측 상단 프로필 아이콘 → Settings
  2. Security 탭 → 아래로 스크롤해 Personal access tokens
  3. Generate new token 클릭
  4. 만료일(Expiration)을 정하고 Scopes에서 **file_content:read**와 **file_dev_resources:read**를 체크
  5. 생성된 figd_로 시작하는 문자열을 복사

Figma 설정의 Security 탭 하단 Personal access tokens 섹션 — Generate new token 버튼과 발급된 토큰 목록

권한 화면이 실제로는 이렇게 생겼습니다. 체크박스가 스무 개 넘게 나오는데 MCP가 쓰는 건 두 개뿐입니다.

Generate new token 모달 — Token name, Expiration 드롭다운, Scopes 목록에 current_user:read, file_content:read, file_dev_resources:read 등이 나열된 화면

만료일 기본값이 1 day라서 그대로 두면 다음 날 연결이 끊깁니다. 90 days 정도로 늘려 두세요.

토큰은 생성 직후 한 번만 보여주니 바로 복사해 두세요. 그리고 이 토큰은 워크스페이스의 모든 파일을 읽을 수 있습니다. 회사 계정이라면 개인 계정으로 따로 만들어서 필요한 파일만 초대하는 편이 안전합니다.

2. Claude Code 연동

Framelink 서버를 붙이는 방법입니다. 터미널에서 한 줄이면 됩니다.

claude mcp add figma --env FIGMA_API_KEY=figd_당신의토큰 \
  -- npx -y figma-developer-mcp --stdio

Windows에서는 npx를 직접 호출하면 실행이 안 되는 경우가 있어 cmd /c로 감싸야 합니다.

claude mcp add figma --env FIGMA_API_KEY=figd_당신의토큰 \
  -- cmd /c npx -y figma-developer-mcp --stdio

Claude Code를 다시 띄우고 /mcp를 입력했을 때 figma가 connected로 보이면 끝입니다.

공식 서버를 쓸 거라면 훨씬 짧습니다.

claude mcp add --transport http figma https://mcp.figma.com/mcp

/mcp에서 figma를 골라 OAuth 인증을 마치면 연결됩니다. Figma 데스크톱 앱의 로컬 서버를 쓰는 방법도 있는데, 앱 설정에서 MCP 서버를 켠 다음 로컬 주소를 등록하면 됩니다.

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

로컬 서버 방식은 Figma에서 선택한 프레임을 그대로 인식합니다. URL을 붙여넣을 필요가 없어서 손이 제일 덜 갑니다.

3. Codex 연동

Codex는 CLI 명령 대신 설정 파일을 직접 고칩니다. ~/.codex/config.toml을 열고 아래 블록을 추가하세요.

[mcp_servers.figma]
command = "npx"
args = ["-y", "figma-developer-mcp", "--stdio"]
env = { FIGMA_API_KEY = "figd_당신의토큰" }

공식 원격 서버를 붙이려면 HTTP 방식으로 적습니다.

[features]
rmcp_client = true

[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"

Codex를 재시작한 뒤 확인합니다.

codex mcp list

여기서 상태가 failed로 뜨면 토큰 오타이거나 npx가 PATH에 없는 경우가 대부분입니다. Node를 nvm으로 관리한다면 command에 npx 대신 절대 경로를 적어야 할 수도 있습니다.

4. Gemini CLI와 Cursor

구조는 똑같고 파일 위치만 다릅니다. Gemini CLI는 ~/.gemini/settings.json, Cursor는 프로젝트의 .cursor/mcp.json입니다.

{
  "mcpServers": {
    "figma": {
      "command": "npx",
      "args": ["-y", "figma-developer-mcp", "--stdio"],
      "env": { "FIGMA_API_KEY": "figd_당신의토큰" }
    }
  }
}

토큰을 파일에 직접 박기 싫으면 --figma-api-key=$FIGMA_API_KEY 형태로 넘기고 셸 환경변수에 두는 방법도 있습니다. 어느 쪽이든 이 파일은 .gitignore에 넣으세요.

5. 토큰 없이 쓰는 세 번째 방법 — Talk to Figma

앞의 두 방법은 결국 Figma 서버에 요청을 보냅니다. 그래서 한도든 토큰이든 걸리는 게 생기죠. Talk to Figma는 경로가 아예 다릅니다.

Figma 데스크톱 앱 (플러그인)
        ↕  WebSocket (localhost:3055)
   소켓 서버
        ↕  MCP
Claude Code / Cursor / Codex

Figma 플러그인이 내 컴퓨터에서 도는 WebSocket 서버에 접속하고, 에이전트는 그 채널로 명령을 보냅니다. Figma REST API를 거치지 않으니 개인 액세스 토큰이 필요 없고 호출 한도도 없습니다. 앞에서 경고한 “PAT 하나가 워크스페이스 전체 읽기 권한” 문제를 구조적으로 피해 갑니다.

설치는 Bun 기반입니다.

curl -fsSL https://bun.sh/install | bash
bun setup    # 저장소에서 실행. MCP 설정까지 같이 잡아준다
bun socket   # WebSocket 서버 기동 → "WebSocket server running on port 3055"

MCP 설정은 토큰이 없어서 훨씬 짧습니다.

{
  "mcpServers": {
    "TalkToFigma": {
      "command": "bunx",
      "args": ["cursor-talk-to-figma-mcp@latest"]
    }
  }
}

Claude Code라면 한 줄로도 됩니다.

claude mcp add TalkToFigma -- bunx cursor-talk-to-figma-mcp@latest

마지막으로 Figma 커뮤니티 플러그인을 설치해 실행하고, 에이전트에서 join_channel로 채널에 들어가면 연결이 끝납니다. 채널 참여를 먼저 하지 않으면 이후 명령이 전부 실패하니 이 순서를 지키세요.

여기서만 되는 일이 있습니다. 텍스트를 한꺼번에 바꾸거나, 컴포넌트 인스턴스의 오버라이드를 여러 대상에 전파하는 것처럼 디자인 파일을 고치는 작업이요. 읽기 전용인 앞의 두 방법으로는 안 됩니다.

대신 조건이 붙습니다. Figma 데스크톱 앱이 필요하고, 작업하는 내내 소켓 서버와 플러그인을 띄워두어야 합니다. 팀원마다 각자 설치해야 하는 것도 부담이고요. 시안을 코드로 옮기기만 할 거면 굳이 이 구성까지 갈 필요는 없습니다.

6. 실제로 쓸 때

연결만 해두면 알아서 되는 건 아닙니다. Figma에서 프레임을 선택하고 우클릭해 Copy link to selection으로 얻은 URL을 프롬프트에 넣어야 합니다. URL 끝의 node-id가 어떤 프레임인지 알려주는 좌표라서 이게 없으면 파일 전체를 긁어옵니다.

Figma 파일 목록에서 파일 카드를 우클릭했을 때 나오는 메뉴 — Open, Create new branch, Copy link, Share, Duplicate 항목

주의할 게 하나 있습니다. 파일 목록에서 우클릭해 나오는 Copy link는 파일 전체 링크라 node-id가 붙지 않습니다. 프레임 단위 링크는 파일을 연 다음 캔버스에서 프레임을 선택하고 우클릭해야 나옵니다.

이 프레임을 Tailwind + React 컴포넌트로 만들어 줘.
https://www.figma.com/design/AbCdEf/Project?node-id=123-456
기존 Button 컴포넌트를 재사용하고 색상은 tokens.css 변수를 써.

시안 URL만 던지면 LLM은 픽셀값을 그대로 하드코딩한 코드를 뱉습니다. 기존 컴포넌트와 토큰을 쓰라고 명시하는 게 재작업을 줄이는 지점인데, 이 부분은 바이브 코딩 프롬프트에 더 자세히 적어 뒀습니다.

7. 자주 걸리는 함정

429 Too Many Requests. 무료 플랜에서 Framelink로 몇 시간 작업하면 만나게 됩니다. MCP 서버 문제가 아니라 Figma REST API 한도라서 기다리는 것 외엔 방법이 없습니다. 프레임 단위로 잘게 요청하면 한도를 덜 씁니다.

공식 서버가 금방 멈춤. Starter 플랜은 월 20회, 유료 플랜의 View/Collab 시트는 월 6회에서 걸립니다. 플랜보다 시트 종류를 먼저 확인하세요.

컨텍스트 폭발. 큰 페이지 전체를 요청하면 JSON이 수만 토큰으로 돌아옵니다. 항상 node-id로 프레임을 특정하세요.

토큰 유출. PAT 하나가 워크스페이스 전체 읽기 권한입니다. 설정 파일을 커밋하지 말고 안 쓰는 토큰은 Settings에서 바로 폐기하세요.

정리

무료로 Figma를 LLM에 붙이는 현실적인 답은 Framelink + 개인 액세스 토큰입니다. 토큰을 발급하기 꺼려지거나 에이전트가 Figma를 직접 고치게 하고 싶다면 Talk to Figma 쪽이고요. Claude Code는 claude mcp add 한 줄, Codex는 config.toml 네 줄이면 끝나고 나머지 도구도 JSON 위치만 다릅니다. 붙인 뒤 연결 상태와 컨텍스트 점유율은 /mcp와 /context로 확인하면 되고, 그 명령어들은 슬래시 명령어 정리에 모아 뒀습니다. 팀이 Professional 플랜을 쓰고 있다면 공식 서버가 더 정확하니 그쪽을 쓰시고요.

붙이는 데 걸리는 시간은 5분인데, 정작 시간이 드는 건 시안을 어떤 단위로 쪼개서 요청할지 정하는 쪽입니다.