custom-figma-mcp

A lightweight local MCP (Model Context Protocol) 서버로, AI 코딩 에이전트(예: OpenCode)에게 Figma 파일의 구조화된 읽기 전용 접근 권한을 제공합니다 — 파일 계층, 노드 속성, 렌더링된 이미지까지 — Figma의 호스팅/원격 MCP 통합 없이도 사용할 수 있습니다.

왜 필요한가

Figma의 공식 원격 MCP 서버는 허용 목록에 등록된 Client ID 뒤에 제한되어 있어, 개별 개발자가 자신의 에이전트 도구를 연결하기에는 실용적이지 않습니다. 이 프로젝트는 개인 액세스 토큰을 사용해 Figma의 공개 REST API에 직접 통신하고, 표준 MCP 도구 인터페이스를 통해 stdio로 에이전트에 노출함으로써 이 문제를 우회합니다.

Related MCP server: figma-mcp

아키텍처

OpenCode (MCP client)
      │  stdio (JSON-RPC)
      ▼
custom-figma-mcp (this server)
      │  HTTPS + X-Figma-Token
      ▼
Figma REST API (api.figma.com/v1)

이 서버는 단일 Node.js 프로세스로, 다음을 수행합니다:

1. 시작되면 @modelcontextprotocol/sdk를 사용해 stdio 위에 자신을 등록합니다.

2. ListToolsRequestSchema를 통해 MCP 클라이언트(OpenCode)에 고정된 도구 세트를 광고합니다.

3. CallToolRequestSchema를 통해 도구 호출을 실행하고, 개인 액세스 토큰을 헤더로 첨부하여 Figma의 REST API에 프록시합니다.

4. 구조화된 JSON(또는 이미지 URL)을 호출한 에이전트에 반환합니다.

읽기 전용 범위의 토큰으로 GET 요청만 사용하기 때문에, Figma에서 어떤 것도 수정, 댓글 작성, 삭제할 수 없습니다 — 설계상 엄격히 읽기 전용입니다.

노출되는 도구

get_figma_file_structure

파일의 페이지/프레임 계층을 반환하며, 깊이 제한을 두어 전체 노드 트리를 덤프하지 않습니다(대형 파일의 경우 수만 개의 노드가 될 수 있음).

입력:

{ "fileKey": "string", "depth": 2 }

매핑: GET /v1/files/:fileKey?depth=:depth

get_figma_node_details

특정 노드 ID의 전체 속성을 가져옵니다 — 자동 레이아웃 구성, 패딩/갭 값, 채우기, 획, 타이포그래피, 제약 조건, 컴포넌트 속성 등. 정확한 코드 생성을 위한 기본 도구입니다.

입력:

{ "fileKey": "string", "nodeIds": ["1:2", "104:15"] }

매핑: GET /v1/files/:fileKey/nodes?ids=1:2,104:15

get_figma_node_image

특정 노드를 PNG로 렌더링하고 임시 서명 URL을 반환합니다. 생성된 코드를 디자인과 시각적으로 교차 확인할 때 유용합니다.

입력:

{ "fileKey": "string", "nodeId": "104:15", "scale": 2 }

매핑: GET /v1/images/:fileKey?ids=104:15&scale=2

도구를 하나가 아닌 세 개로 분리한 이유

Figma 파일은 엄청나게 클 수 있습니다 — 깊이 제한 없이 GET /files/:key를 단 한 번 호출해도 수 메가바이트의 깊게 중첩된 JSON이 반환되어 LLM의 컨텍스트 창을 즉시 고갈시킵니다. 인터페이스를 세 개의 목표 지향 도구로 분리하면 에이전트는 다음을 수행할 수 있습니다:

1. 먼저 가벼운 개요(get_figma_file_structure)를 얻어 관련 프레임/노드를 식별합니다.

2. 필요한 특정 노드에만 상세히 들어갑니다(get_figma_node_details).

3. 시각적 확인이 필요할 때만 선택적으로 이미지를 렌더링합니다(get_figma_node_image).

이는 인간 개발자가 디자인을 검토하는 방식 — 먼저 훑어본 다음 확대하는 방식 — 을 반영하며, 전체 파일을 한 번에 흡수하지 않습니다.

인증

인증은 file_content:read 범위의 Figma 개인 액세스 토큰(PAT)을 사용합니다. 토큰은 로컬 .env 파일에서 로드되며(절대 하드코딩되지 않음), 모든 외부 요청에 X-Figma-Token 헤더로 첨부됩니다. 토큰은 api.figma.com으로의 직접 요청을 제외하고는 로컬 머신을 벗어나지 않습니다.

오류 처리

모든 도구 핸들러는 try/catch로 감싸져 있습니다. 실패 시(잘못된 파일 키, 접근 권한 없음, 속도 제한 등) 서버는 MCP 호환 오류 응답을 반환합니다:

{
  "content": [{ "type": "text", "text": "Figma API Error: <details>" }],
  "isError": true
}

이를 통해 호출한 에이전트는 조용히 충돌하는 대신 실제 실패 원인을 확인할 수 있습니다.

프로젝트 구조

custom-figma-mcp/
├── index.js        # server entrypoint — tool definitions + handlers
├── package.json    # dependencies, "type": "module" for ESM imports
├── .env            # local only — holds FIGMA_PAT, never committed
└── .gitignore

로컬 개발

디버깅을 위해 서버를 직접 실행합니다(stdio로 통신하므로 일반적인 HTTP 서버 로그는 보이지 않습니다):

node index.js

실제로는 수동으로 실행하지 않습니다 — OpenCode가 opencode.json에 정의된 command를 기반으로 하위 프로세스로 서버를 실행합니다.

이 서버 확장하기

새 도구를 추가하려면:

1. ListToolsRequestSchema가 반환하는 tools 배열에 해당 스키마를 추가합니다.

2. CallToolRequestSchema 핸들러 내부에 일치하는 if (name === "...") 분기를 추가합니다.

3. figmaApi(기본 URL과 인증 헤더가 사전 구성된 axios 인스턴스) 아래의 관련 Figma REST 엔드포인트에 매핑합니다.

새 도구는 읽기 전용으로 유지하고 범위를 제한하세요 — 가능하면 필터링되지 않은 전체 API 응답을 덤프하지 말아 에이전트의 컨텍스트 사용량을 낮게 유지하세요.