F_MCP - Claude Code x Figma MCP Bridge

Claude Code에서 Figma를 직접 제어하는 MCP(Model Context Protocol) 브릿지입니다. grab/cursor-talk-to-figma-mcp를 포크하여 이미지 삽입, 레지스트리 패턴, Claude Code 스킬 등을 추가한 확장 버전입니다.

Architecture

Claude Code
    |
    |--- MCP (stdio) ---> mcp-server      (도구 등록 + WebSocket 중계)
    |                         |
    |--- MCP (stdio) ---> mcp-ws-image    (이미지 fetch + base64 변환)
    |                         |
    +---- WebSocket (port 3055) ----------> Figma Plugin (code.ts)
                                                |
                                            Figma API

3-Layer 구조

Layer	경로	역할
MCP Server	mcp-server/	Claude Code와 Figma 중계. registry 패턴으로 도구 자동 등록
Image MCP Server	mcp-ws-image/	이미지 URL fetch -> base64 변환 -> WebSocket 전달 (별도 MCP)
Figma Plugin	figma-plugin/	Figma 내부 API 실행. base64 이미지 디코딩 + 적용

Why Custom?

공식 cursor-talk-to-figma-mcp에는 이미지 삽입 기능이 없습니다.

Figma 플러그인 샌드박스는 외부 CDN에 직접 접근할 수 없기 때문에:

1. MCP 서버에서 이미지를 fetch
2. base64로 인코딩하여 WebSocket으로 전달
3. 플러그인에서 디코딩 후 figma.createImage() 호출

이 우회 경로를 구현한 것이 이 프로젝트의 핵심입니다.

Quick Start

1. 의존성 설치

# MCP Server
cd mcp-server && npm install && npm run build

# Image MCP Server
cd mcp-ws-image && npm install && npm run build

# Figma Plugin
cd figma-plugin && npm install && npm run build

2. Figma Plugin 등록

Figma Desktop App에서:

1. Menu > Plugins > Development > Import plugin from manifest
2. figma-plugin/manifest.json 선택
3. 플러그인 실행 후 Connect 클릭 -> 채널명 확인 (예: c32c7nbc)

3. MCP 서버 등록

프로젝트 루트의 .mcp.json:

{
  "mcpServers": {
    "set_node_image_fill": {
      "command": "node",
      "args": ["./mcp-ws-image/dist/index.js"]
    }
  }
}

Note: TalkToFigma MCP는 별도로 npm 글로벌 설치하거나, mcp-server/dist/index.js를 등록합니다.

4. Claude Code에서 사용

# 채널 연결
> join_channel("c32c7nbc")

# 프레임 생성
> create_frame(x=0, y=0, width=1080, height=1080, name="Banner")

# 이미지 적용
> set_node_image_fill(channel="c32c7nbc", nodeId="44:56", imageUrl="https://...")

Project Structure

F_MCP/
├── mcp-server/                 # MCP Server (도구 중계)
│   └── src/
│       ├── index.ts            # 서버 엔트리포인트
│       ├── registry.ts         # 커맨드 레지스트리 (Single Source of Truth)
│       ├── tools/index.ts      # registry -> MCP 도구 자동 등록
│       ├── types/commands.ts   # 타입 자동 추출
│       ├── http/server.ts      # HTTP 서버
│       └── queue/              # 커맨드 큐
│
├── mcp-ws-image/               # Image MCP Server (이미지 전용)
│   └── src/
│       └── index.ts            # fetch -> base64 -> WebSocket
│
├── figma-plugin/               # Figma Plugin
│   ├── manifest.json           # 플러그인 메타 + 네트워크 허용 도메인
│   └── src/
│       ├── code.ts             # Figma API 핸들러 (set_image_fill 포함)
│       └── ui.ts               # WebSocket UI
│
├── .claude/
│   └── skills/                 # Claude Code Skills
│       ├── channel-specs/      # 마케팅 채널별 이미지 사이즈 규격표
│       └── add-figma-command/  # 새 커맨드 추가 가이드
│
├── .mcp.json                   # MCP 서버 등록 설정
└── .gitignore

Adding New Commands

registry.ts + code.ts 2개 파일만 수정하면 됩니다.

Step 1: mcp-server/src/registry.ts에 커맨드 추가

export const commandRegistry = {
  // ... 기존 커맨드들
  my_new_command: {
    description: 'Description for Claude Code',
    schema: z.object({
      nodeId: z.string().describe('Figma node ID'),
      // ... 파라미터
    })
  }
};

Step 2: figma-plugin/src/code.ts에 핸들러 추가

case 'my_new_command': {
  const node = figma.getNodeById(msg.nodeId);
  // Figma API 호출
  figma.ui.postMessage({
    type: 'result', success: true,
    nodeId: msg.nodeId, commandId: msg.commandId
  });
  break;
}

Step 3: 빌드

cd mcp-server && npm run build
cd figma-plugin && npm run build

도구 자동 등록(tools/index.ts)이 처리하므로 다른 파일 수정은 불필요합니다.

Claude Code Skills

이 프로젝트에는 Claude Code에서 자동 인식되는 스킬이 포함되어 있습니다.

Skill	용도	호출
channel-specs	마케팅 채널별 이미지 사이즈 규격 (구글, 네이버, 무신사, Meta 등)	/channel-specs
add-figma-command	새 Figma 커맨드 추가 가이드	/add-figma-command

Clone 후 Claude Code로 열면 자동으로 사용 가능합니다.

Registered MCP Tools

mcp-server (TalkToFigma)

Tool	Description
create_rect	사각형 생성
create_text	텍스트 생성
create_frame	프레임(컨테이너) 생성
create_image	URL 이미지로 새 프레임 생성
set_fill	노드 채우기 색상 변경
set_image_fill	기존 노드에 이미지 URL 적용
move_node	노드 위치 이동
delete_node	노드 삭제

mcp-ws-image (Image Fill)

Tool	Description
set_node_image_fill	URL에서 이미지 fetch -> base64 변환 -> Figma 노드에 적용

Image Flow Detail

1. Claude Code: set_node_image_fill(channel, nodeId, imageUrl)
2. mcp-ws-image: fetch(imageUrl) -> arrayBuffer -> base64
3. WebSocket:    { command: "set_image_fill", params: { nodeId, imageBase64, scaleMode } }
4. Figma Plugin: base64 decode -> Uint8Array -> figma.createImage(bytes)
5. Figma:        node.fills = [{ type: 'IMAGE', imageHash, scaleMode: 'FILL' }]

Figma 플러그인 샌드박스에는 atob()이 없으므로 커스텀 base64 디코더를 사용합니다.

Network Access

figma-plugin/manifest.json의 networkAccess.allowedDomains에 허용된 도메인:

• ws://localhost:3055 (WebSocket 서버)
• https://static-resource-mall.fnf.co.kr
• https://static-resource.mlb-korea.com

새 도메인의 이미지를 사용하려면 이 목록에 추가 후 플러그인을 다시 빌드하세요.

Credits

• Original: grab/cursor-talk-to-figma-mcp
• License: MIT