# F_MCP - Claude Code x Figma MCP Bridge
Claude Code에서 Figma를 직접 제어하는 MCP(Model Context Protocol) 브릿지입니다.
[grab/cursor-talk-to-figma-mcp](https://github.com/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. 의존성 설치
```bash
# 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`:
```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`에 커맨드 추가
```typescript
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`에 핸들러 추가
```typescript
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: 빌드
```bash
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](https://github.com/grab/cursor-talk-to-figma-mcp)
- License: MIT
