F_MCP Server

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 구조

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에서 자동 인식되는 스킬이 포함되어 있습니다.

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

Registered MCP Tools

mcp-server (TalkToFigma)

mcp-ws-image (Image Fill)

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, imageB