# 피그마 연결

Windows에서 **Talk to Figma MCP**(로컬, 무료)로 Claude Code, Claude Desktop, Codex를 피그마 데스크톱 앱에 붙이는 앱입니다. 설치와 업데이트는 `setup.exe` 하나로 합니다. 관리자 권한은 필요 없습니다.

지원: Windows 10 이상 64비트.

## 설치

1. GitHub Release 페이지에서 최신 `figma-bridge-<버전>-setup.exe` 를 받습니다.
2. 실행합니다. Windows가 "Windows의 PC 보호" 창을 띄우면 **추가 정보** → **실행** 을 누릅니다. 이 앱은 코드 서명을 하지 않아서 이 경고가 뜹니다.
   - **Windows 11 의 스마트 앱 컨트롤(Smart App Control)이 켜져 있으면** 위 창이 뜨지 않고 앱이 아예 실행되지 않습니다. 스마트 앱 컨트롤에는 앱별 예외 기능이 없어서 **추가 정보 → 실행** 도 소용없습니다. 피하려면 Windows 보안 > 앱 및 브라우저 컨트롤에서 스마트 앱 컨트롤을 끄는 방법뿐인데, 한 번 끄면 Windows 를 다시 설치하기 전에는 다시 켤 수 없습니다. 끌지 말지는 사용자가 정할 일이고, 이 앱은 현재 의도적으로 서명 없이 배포됩니다.
3. 설치가 끝나면 바탕화면과 시작 메뉴에 **피그마 연결** 바로가기가 생깁니다.

피그마를 시킬 AI 도구가 이 PC 에 하나는 있어야 합니다. 없으면 앱의 **AI 도구 설치** 를 누르세요. winget 으로 먼저 시도하고, 안 되면 공식 설치 스크립트로 물러섭니다.

| | winget 장치 ID | 설치 안 될 때 |
|---|---|---|
| Claude Code (권장) | `Anthropic.ClaudeCode` | https://docs.claude.com/en/docs/claude-code/setup |
| Codex CLI | `OpenAI.Codex` | https://developers.openai.com/codex/cli |
| Claude Desktop | `Anthropic.Claude` | https://claude.ai/download |

**로그인은 대신 해 드릴 수 없습니다.** AI 도구 목록의 **로그인** 버튼이 터미널을 열어 주면, 거기서 각자 계정으로 로그인하세요.

## 사용

1. 피그마에서 디자인 파일을 하나 열어 둡니다.
2. **연동** 버튼을 누릅니다. 중계 서버를 켜고, 설치된 AI 도구에 MCP 항목을 넣고, 피그마 플러그인을 붙입니다.
3. 상태 줄이 초록색 **연결됨** 이 되면 끝입니다. 이후 AI 도구에서 피그마를 바로 쓸 수 있습니다.

Claude Desktop 은 설정 파일을 앱 시작 때 읽습니다. 연동 뒤 Claude Desktop 에서 피그마 도구가 보이지 않으면 Claude Desktop 을 한 번 재시작하세요.

연동 버튼이 켜기 스위치 역할도 합니다. 연동이 끝나면 같은 자리에 **끄기** 버튼이 나옵니다.

### 세 가지 상태

| 상태 | 뜻 | 화면 |
|---|---|---|
| 꺼짐 | 중계 서버가 멈춰 있습니다. | 회색, **연동** |
| 플러그인 미연결 | 중계 서버와 MCP 설정은 준비됐지만 피그마 플러그인이 붙지 않았습니다. 앱을 다시 켰을 때 주로 보입니다. | 주황색, **플러그인 연결** |
| 연결됨 | 중계 서버가 켜져 있고 플러그인이 붙어 있습니다. | 초록색, **끄기** |

피그마에서 디자인 파일을 닫으면 상태가 플러그인 미연결로 돌아갑니다. 다시 열고 플러그인이 붙으면 연결됨이 됩니다.

### 플러그인

플러그인이 설치되어 있지 않으면, 연동 중에 피그마 앱 안에서 플러그인 설치 페이지가 열립니다. 페이지에서 **Run** 을 한 번 누른 뒤 앱에서 **연동** 을 다시 누르세요.

플러그인: https://www.figma.com/community/plugin/1485687494525374295/talk-to-figma-mcp-plugin

앱을 켤 때와 Windows에 로그인할 때는 피그마를 실행하지 않고, 플러그인도 붙이지 않습니다. 플러그인은 **연동** 또는 **플러그인 연결** 버튼을 누를 때만 붙입니다.

### 채널 이름

플러그인이 채널 이름을 새로 만들어도 맞출 필요가 없습니다. AI에게 "피그마 보여?" 라고 물으면 됩니다.

## 설정과 트레이

- **Windows 로그인 시 자동 시작**: 기본값은 꺼짐입니다. 켜면 창 없이 트레이에서 조용히 시작합니다.
- 창의 X 를 눌러도 앱은 종료되지 않고 트레이로 내려갑니다. 트레이 메뉴에서 연동, 끄기, 플러그인 연결, 창 열기, 종료를 할 수 있습니다.
- **점검**: 중계 서버, 피그마, 플러그인, AI 도구의 MCP 등록을 확인하고 고칩니다. **고치기** 는 적용한 조치를 목록 맨 위에 보여 줍니다.
- **AI 점검**: 점검으로 해결되지 않을 때 로컬 Claude Code 또는 Codex에 맡깁니다.

## 업데이트

앱을 시작할 때 새 버전이 있는지 한 번 확인합니다. 새 버전이 있으면 창과 트레이에 알림이 뜨지만, 다운로드는 사용자가 **다운로드** 를 눌러야 시작합니다. 다운로드가 끝나면 **재시작 후 설치** 를 눌러 설치합니다. 설정에서 **업데이트 확인** 으로 다시 확인할 수 있습니다.

설치 후 재시작하면 마지막 스위치 값이 켜짐이었을 때 중계 서버만 다시 켜집니다. 피그마는 실행하지 않으며, 플러그인은 **플러그인 연결** 을 누를 때 붙습니다.

## 끄기와 제거

**끄기** 는 중계 서버를 멈춥니다. Claude Code, Claude Desktop, Codex 설정의 TalkToFigma 항목은 그대로 둡니다. 그래서 끈 동안 AI 도구는 연결이 끊긴 것으로만 보이고, 다시 켜면 곧바로 복구됩니다.

제거는 Windows 설정 > 앱 > 설치된 앱에서 **피그마 연결** 을 고릅니다. 제거하면 Claude Code, Claude Desktop, Codex 설정에서 TalkToFigma 항목도 지웁니다. 로그와 설정 파일(`%LOCALAPPDATA%\FigmaBridge`)을 지울지는 제거 화면에서 묻습니다.

## 문제 해결

- **3055 포트를 다른 프로그램이 쓰고 있습니다**: 연동 버튼 아래에 이유가 나옵니다. 그 프로그램을 끈 뒤 다시 누르세요.
- **이전 PowerShell 버전(`설치.cmd`)에서 올라왔습니다**: 이전 버전이 남긴 중계 프로세스는 `/status` 가 피그마 연결 릴레이이고 `socket.pid` 가 그 프로세스를 가리킬 때만 앱이 자동으로 멈춥니다. 확인되지 않은 다른 프로그램이 3055를 쓰면 위의 포트 안내가 나옵니다.
- 명령줄에서 상태를 보려면 설치 폴더의 `figma-bridge.exe --status` 를 실행합니다. 기본 설치 위치는 `%LOCALAPPDATA%\Programs\피그마 연결` 입니다. 앱이 꺼져 있으면 `relay` 가 `null` 입니다.
- `figma-bridge.exe --doctor-fix` 는 피그마에 아무 입력도 보내지 않고 중계 서버와 MCP 항목을 고칩니다.
- `figma-bridge.exe --cleanup` 은 MCP 항목만 지웁니다. 제거 과정에서 설치 프로그램이 이 명령을 실행합니다.

런타임 데이터와 로그는 `%LOCALAPPDATA%\FigmaBridge` 에 있습니다. `FIGMA_BRIDGE_HOME` 환경 변수를 설정하면 그 경로를 씁니다.