# Figma MCP Connect

Figma MCP Connect는 Cursor, Claude Code, Codex 같은 MCP 클라이언트가 Figma 문서를 읽고 수정하도록 연결하는 로컬 Node.js 브리지입니다.

```text
MCP 클라이언트
    ↕ stdio
MCP 서버 (Node.js, 로컬 릴레이 자동 시작/재사용)
    ↕ WebSocket (127.0.0.1:3055)
Figma 개발 플러그인
```

MCP 서버가 로컬 WebSocket 릴레이를 직접 관리합니다. Figma 플러그인도 실행 시 자동으로 릴레이와 채널에 연결되며, 열린 플러그인이 하나라면 MCP 서버가 그 채널을 자동 선택합니다. 평소에는 `npm run socket`이나 `join_channel`을 직접 실행할 필요가 없습니다.

> [!IMPORTANT]
> `figma-mcp-connect` npm 패키지는 아직 배포되지 않았습니다. 현재는 `npm run setup`으로 이 저장소를 로컬 빌드하고, 생성된 `dist/server.js`를 MCP 클라이언트에서 실행하세요.

## 요구 사항

- Node.js 18 이상
- npm과 Git
- Figma 데스크톱 앱
- MCP를 지원하는 클라이언트(Cursor, Claude Code, Codex 등)

```bash
node --version
npm --version
git --version
```

## 처음 한 번만 설정

### 1. 설치, 빌드, MCP 등록

```bash
git clone https://github.com/Sangwonee/figma-mcp-connect.git
cd figma-mcp-connect
npm run setup
```

`npm run setup`은 다음 작업을 한 번에 수행합니다.

- `npm ci`로 의존성 설치
- `dist/server.js`와 `dist/socket.js` 빌드
- 현재 저장소의 `dist/server.js` 절대 경로를 `.cursor/mcp.json`과 `.mcp.json`에 기록

생성되는 설정은 공개 npm 패키지가 아니라 로컬 Node.js 빌드를 가리킵니다.

```json
{
  "mcpServers": {
    "FigmaMCPConnect": {
      "command": "node",
      "args": [
        "/absolute/path/to/figma-mcp-connect/dist/server.js"
      ]
    }
  }
}
```

Cursor는 프로젝트의 `.cursor/mcp.json`, Claude Code는 프로젝트 루트의 `.mcp.json`을 사용합니다. 다른 MCP 클라이언트에서는 같은 `command`와 절대 경로를 해당 클라이언트 설정에 등록하세요. 설정 후 MCP 클라이언트를 다시 시작하거나 MCP 서버 목록을 새로고침합니다.

### 2. Figma 개발 플러그인 등록

1. Figma에서 작업할 파일을 엽니다.
2. `Plugins → Development → New Plugin`으로 이동합니다.
3. `Link existing plugin` 또는 `Import plugin from manifest`를 선택합니다.
4. 이 저장소의 `src/cursor_mcp_plugin/manifest.json`을 선택합니다.
5. 개발 플러그인 목록에 **Figma MCP Connect**가 나타나는지 확인합니다.

플러그인은 별도 번들 없이 `code.js`와 `ui.html`을 직접 사용합니다.

## 평소 사용법

초기 설정을 마친 뒤에는 다음 순서만 따르면 됩니다.

1. 설정한 프로젝트를 Cursor, Claude Code 또는 다른 MCP 클라이언트에서 엽니다.
2. 작업할 Figma 파일에서 개발 플러그인 **Figma MCP Connect**를 실행합니다.
3. 플러그인이 자동으로 `127.0.0.1:3055` 릴레이에 연결될 때까지 잠시 기다립니다.
4. MCP 클라이언트에 Figma 작업을 자연어로 요청합니다.

```text
현재 Figma 문서 구조를 확인해줘.
현재 선택한 프레임을 분석해줘.
선택한 텍스트를 "여행 일정"으로 바꿔줘.
선택한 노드 이름을 Hero Section으로 변경해줘.
```

MCP 서버가 시작될 때 로컬 릴레이가 없으면 내장 릴레이를 자동으로 시작하고, 이미 정상 릴레이가 실행 중이면 재사용합니다. 플러그인은 자동으로 임의 채널에 참가합니다. 연결된 Figma 플러그인이 하나라면 MCP 서버도 그 채널에 자동 참가하므로 수동 채널 입력이 필요 없습니다.

MCP 서버는 MCP 클라이언트가 관리하므로 별도 터미널에서 `npm start`를 실행하지 않습니다. Figma 플러그인 창은 작업 중 열어 두세요.

## 여러 Figma 플러그인을 동시에 열 때

두 개 이상의 Figma 파일에서 플러그인을 열면 MCP 서버가 어느 파일을 사용할지 임의로 고르지 않습니다. 각 플러그인 화면에 표시된 채널 중 원하는 채널을 `join_channel`로 선택하세요.

```text
Figma MCP Connect의 join_channel 도구로 a1b2c3d4 채널에 연결해줘.
연결되면 get_document_info로 문서 구조를 확인해줘.
```

플러그인 실행 중 자동 재연결될 때는 채널이 유지됩니다. 플러그인을 완전히 닫았다가 새로 실행하면 채널이 바뀔 수 있으므로, 여러 플러그인을 사용하는 중이라면 최신 채널 이름으로 `join_channel`을 호출하세요.

## 수동 릴레이 실행과 진단

일반 사용에는 필요하지 않지만, 연결 문제를 진단하거나 릴레이를 독립 프로세스로 유지하려면 저장소 루트에서 실행합니다.

```bash
npm run socket
```

MCP 서버는 `127.0.0.1:3055`의 상태를 확인한 뒤 이 릴레이가 Figma MCP Connect 릴레이라면 자동으로 재사용합니다. 정상 상태는 다음 명령으로 확인할 수 있습니다.

```bash
curl http://127.0.0.1:3055/health
```

수동 릴레이를 종료하려면 해당 터미널에서 `Ctrl+C`를 누릅니다. 현재 Figma 플러그인 manifest와 기본 MCP 연결은 포트 `3055`를 기준으로 하므로 특별한 이유가 없으면 포트를 바꾸지 마세요.

## 권장 작업 순서

Figma 문서를 안전하게 다루려면 다음 순서를 권장합니다.

1. `get_document_info`로 현재 문서 구조를 확인합니다.
2. `get_selection` 또는 `read_my_design`으로 선택 영역을 읽습니다.
3. 필요한 생성·수정 도구를 실행합니다.
4. `get_node_info` 또는 이미지 내보내기로 결과를 확인합니다.

여러 노드를 변경할 때는 단일 도구를 반복하기보다 `set_multiple_text_contents`, `delete_multiple_nodes`, `set_multiple_annotations` 같은 일괄 처리 도구를 우선 사용하세요.

## 주요 MCP 도구

| 범주 | 주요 도구 | 용도 |
| --- | --- | --- |
| 연결 | `join_channel` | 여러 플러그인 중 사용할 채널을 수동 선택 |
| 문서·선택 | `get_document_info`, `get_selection`, `read_my_design`, `get_node_info`, `get_nodes_info` | 문서와 노드 구조 조회 |
| 선택·포커스 | `set_focus`, `set_selections` | 캔버스에서 노드 선택 및 화면 이동 |
| 요소 생성 | `create_frame`, `create_rectangle`, `create_section`, `create_text` | 프레임, 도형, 섹션, 텍스트 생성 |
| 텍스트 | `scan_text_nodes`, `set_text_content`, `set_multiple_text_contents` | 텍스트 검색 및 일괄 변경 |
| 오토 레이아웃 | `set_layout_mode`, `set_padding`, `set_axis_align`, `set_layout_sizing`, `set_item_spacing` | 방향, 정렬, 크기, 간격 설정 |
| 스타일 | `set_fill_color`, `set_stroke_color`, `set_corner_radius`, `set_image_fill` | 색상, 테두리, 모서리, 이미지 채우기 설정 |
| 배치·구조 | `move_node`, `resize_node`, `clone_node`, `rename_node`, `set_parent` | 위치·크기·이름·부모 관계 변경 |
| 삭제 | `delete_node`, `delete_multiple_nodes` | 노드 단일 또는 일괄 삭제 |
| 컴포넌트 | `get_local_components`, `create_component_instance`, `get_instance_overrides`, `set_instance_overrides` | 컴포넌트 인스턴스와 오버라이드 관리 |
| 주석 | `get_annotations`, `set_annotation`, `set_multiple_annotations`, `scan_nodes_by_types` | Figma 네이티브 주석 조회 및 생성 |
| 프로토타입·FigJam | `get_reactions`, `set_default_connector`, `create_connections` | 프로토타입 흐름을 조회하고 커넥터 생성 |
| 내보내기 | `export_node_as_image` | 노드를 PNG, JPG, SVG 또는 PDF로 내보내기 |

## 프로젝트 구조

```text
figma-mcp-connect/
├── src/
│   ├── talk_to_figma_mcp/server.ts  # stdio MCP 서버와 자동 연결 관리
│   ├── relay.ts                     # 내장/재사용 가능한 릴레이 구현
│   ├── socket.ts                    # 수동 릴레이 실행 진입점
│   └── cursor_mcp_plugin/
│       ├── manifest.json
│       ├── code.js
│       └── ui.html
├── scripts/setup.sh
├── package.json
└── tsup.config.ts
```

## 개발과 검증

```bash
npm ci
npm run build
npm run dev       # 감시 빌드
npm start         # stdio MCP 서버 직접 실행(개발/진단용)
npm run socket    # 독립 릴레이 실행(진단용)
```

내장 릴레이의 자동 시작, 단일 채널 자동 참가, 다중 MCP 프로세스의 릴레이 인계를 확인하는 통합 테스트가 있습니다. 별도 린터는 구성되어 있지 않습니다.

```bash
npm test
npx tsc --noEmit
node --check dist/server.js
node --check dist/socket.js
```

## 문제 해결

### 플러그인이 연결되지 않음

- MCP 클라이언트에서 `FigmaMCPConnect` 서버가 실행 중인지 확인하고 새로고침합니다.
- 잠시 기다린 뒤 Figma 플러그인을 닫았다가 다시 실행합니다.
- 포트 `3055`를 다른 프로그램이 사용 중인지 확인합니다.
- 진단용으로 `npm run socket`을 실행한 뒤 플러그인을 다시 엽니다.

### `No Figma plugin is connected` 오류

작업할 Figma 파일에서 **Figma MCP Connect** 플러그인을 열고 연결 표시를 확인한 뒤 요청을 다시 실행하세요.

### 여러 플러그인이 연결되었다는 오류

플러그인 화면에서 원하는 채널 이름을 확인하고 `join_channel`로 선택하세요. 하나만 사용할 예정이라면 다른 Figma 플러그인 창을 닫아도 됩니다.

### 소스 변경이 반영되지 않음

```bash
npm run build
```

빌드 후 MCP 클라이언트의 서버를 다시 시작하고 Figma 플러그인도 다시 실행하세요.

### 포트 3055가 다른 서비스에서 사용 중임

MCP 서버는 기존 프로세스가 호환되는 Figma MCP Connect 릴레이일 때만 재사용합니다. 다른 서비스가 포트 `3055`를 사용하고 있다면 해당 프로세스를 종료한 뒤 MCP 서버를 다시 시작하세요.

## 개인정보 관련 안내

Figma 플러그인은 플러그인 실행, 채널 연결, 명령 이름, 성공/실패, 실행 시간에 관한 익명 사용 통계를 Google Analytics로 전송한다고 UI와 manifest에 명시되어 있습니다. 파일 내용은 분석 이벤트에 포함하지 않는다고 안내합니다.

## npm 배포 상태

새 패키지명 `figma-mcp-connect`는 아직 npm에 배포되지 않았습니다. 현재는 `npx -y figma-mcp-connect@latest`를 사용하지 말고 `npm run setup`이 생성한 로컬 Node.js 설정을 사용하세요.

## 라이선스

이 프로젝트는 [MIT 라이선스](./LICENSE)를 따릅니다.