Writable Figma MCP Bridge（Figma 커넥터）

MCP와 호환되는 모든 AI 클라이언트에 Figma 샌드박스 안에서 임의의 JS를 실행할 수 있는 범용 쓰기 채널을 제공합니다. 로컬 실행, 클라우드 없음, 기본적으로 로컬에서만 접근 가능합니다.

대부분의 데스크톱 AI 어시스턴트에서 사용할 수 있으며, 표준 MCP로 연결하면 Figma 파일을 읽고 쓸 수 있습니다.

🌐 언어: 한국어 ｜ English

1. 소개

Figma 커넥터는 로컬 MCP 서비스와 Figma 플러그인의 조합입니다. 어떤 데스크톱 AI 어시스턴트든 표준 MCP 프로토콜을 통해 지금 편집 중인 Figma 파일을 읽고 수정할 수 있게 해 줍니다. 전체 연결 경로는 사용자 컴퓨터(127.0.0.1)에서만 실행되며, 외부 API나 클라우드 서비스에 의존하지 않습니다.

디자인 철학은 「로컬 우선, 감사 가능」 입니다. 전체 경로가 오직 사용자의 머신(127.0.0.1)에서만 실행되고, 외부 API Key나 OAuth가 필요하지 않으며, 코드량이 작고 완전히 감사할 수 있습니다.

Related MCP server: Local Figma MCP Bridge

2. 핵심 기능

• 쓰기 가능한 MCP 브리지: figma_run_js를 신뢰할 수 있는 쓰기 진입점으로 MCP 클라이언트에 노출합니다.

• 안전한 쓰기: 작업 전마다 노드 스냅샷을 만들고, 오류가 발생하면 이번에 새로 생성한 노드를 자동으로 롤백합니다.

• 디자인 시스템 우선: 디자인 시스템 인덱싱, 컴포넌트 임포트, 변수 바인딩, 스타일 적용 등을 위한 helpers를 내장해 하드코딩을 피합니다.

• 상태 시각화: 패널에 「작업 대기 중 / 읽기 중 / 쓰기 중」 세 가지 상태가 실시간으로 표시됩니다(파란색=쓰기, 초록색=읽기).

• 조준 버튼: 각 링크를 한 번 클릭하면 대상 노드로 이동하고 선택합니다(보기 영역 자동 확대/축소).

• 중복 링크 안내: 이미 있는 링크를 붙여넣으면 패널 하단에 「현재 링크는 이미 존재합니다」라는 플로팅 힌트가 나타나 실수를 방지합니다.

• 다중 플러그인 보호: GET /health는 모든 폴링 창을 표시하고, FIGMA_WRITER_STRICT=1로 단일 창 전용 모드를 강제해 여러 창이 잘못된 파일을 수정하는 것을 막습니다.

3. 동작 원리

AI 客户端 (Claude / WorkBuddy)
        │  MCP (http://localhost:8788/mcp)
        ▼
本地 MCP 服务 (server.mjs)  ── 任务入队
        │
        ▲ 轮询 GET /plugin/job
        │
Figma 插件 (code.js 运行在 Figma 沙箱)  ── 在 Figma 内执行读/写
        │ 结果 POST /plugin/result
        ▼
本地 MCP 服务  ── 把结果回传给 AI

1. AI가 MCP로 서버(http://localhost:8788/mcp)를 호출합니다.

2. 서버가 작업을 큐에 넣습니다.

3. Figma 플러그인이 /plugin/job을 폴링해 작업을 가져와 Figma 내부에서 실행합니다(현재 열려 있는 파일만 조작할 수 있습니다).

4. 플러그인은 POST /plugin/result로 결과를 AI에게 돌려줍니다.

⚠️ 플러그인의 실제 읽기/쓰기 경계는 「Figma에 현재 열려 있는 문서」입니다. 패널에서 선택한 링크는 어느 파일을 대상으로 작업하고 있는지 서버/AI에 보고하는 용도입니다. 둘이 일치하지 않아도 읽기/쓰기는 현재 열려 있는 파일을 기준으로 이루어집니다.

4. 요구 사항

• Node.js ≥ 18(로컬 MCP 서비스 실행에 필수이며, nodejs.org에서 다운로드해 설치합니다).

• Figma 데스크톱 앱(웹 버전은 로컬 플러그인/dev 모드를 지원하지 않습니다).

• API Key 불필요, OAuth 불필요, 인터넷 연결 불필요(서비스는 127.0.0.1에서만 실행됩니다).

5. 빠른 시작

1. 로컬 서비스 시작

방법 A: 명령줄(권장, 로그 보기에 편리함)

cd writable-figma-mcp-bridge
node server.mjs

방법 B: 실행기 더블 클릭

• macOS: 저장소의 start.command 더블클릭

• Windows: start.bat 더블클릭

더블클릭하면 스크립트가 「최소화/백그라운드」 상태로 node server.mjs를 실행하므로 명령어를 입력할 필요가 없습니다. 로컬에 Node.js가 설치되어 있어야 합니다.

시작 후 기본 주소는 127.0.0.1:8788이며 로컬에서만 접근할 수 있고, 기본적으로 유일한 도구인 figma_run_js를 노출합니다.

2. Figma에서 플러그인 수동 설치(중요)

Figma 플러그인은 이 저장소의 manifest.json을 수동으로 불러와야 합니다. 절차는 다음과 같습니다.

1. Figma 데스크톱 앱을 엽니다(공식 지원 macOS / Windows).

2. 아무 Figma 디자인 파일을 엽니다.

3. 상단 메뉴에서 Plugins（插件） → Development（开发） → Import plugin from manifest…（从清单导入插件…）를 선택합니다.

4. 파일 선택 창에서 이 저장소의 manifest.json(위치: writable-figma-mcp-bridge/manifest.json)을 선택합니다.

5. 메뉴에서 Plugins（插件） → Development（开发） → Writable Figma MCP Bridge를 실행합니다.

6. 표시된 패널에서 **「시작」**을 클릭해 로컬 서비스에 연결합니다.

「시작」이 활성화되고 상태가 「작업 대기 중…」으로 표시되면 플러그인이 연결된 것입니다. 이후 AI가 MCP로 전달하는 모든 읽기/쓰기 작업은 현재 열려 있는 파일에 적용됩니다.

3. MCP 클라이언트 설정

일반적인 경우에는 로컬 서비스 포트가 통신되고 Figma 플러그인이 설치되어 있으면 별도 설정 없이 바로 연결할 수 있습니다.

연결이 되지 않는다면 MCP 클라이언트에 아래 설정을 직접 추가하세요(URL은 실제 포트를 가리켜야 합니다):

{
  "mcpServers": {
    "figma-writer": {
      "type": "http",
      "url": "http://localhost:8788/mcp"
    }
  }
}

기본 포트는 8788입니다. 포트가 이미 사용 중이면 서비스가 자동으로 다음 포트로 변경하므로, 시작 로그에 표시된 실제 주소를 확인하세요. 포트가 변경되었다면 위 URL의 포트 부분만 실제 포트로 바꾸면 됩니다.

6. 기능 설명

링크 관리

• 위쪽 입력 창에 Figma 파일 링크를 붙여넣고 「추가」를 누르면 아래 목록에 등록됩니다.

• 각 줄은 현재 활성 링크로 「선택」할 수 있으며(폴링 시 서버에 보고됨), 「조준」 버튼이 함께 제공됩니다.

• 이미 존재하는 링크를 붙여넣으면 패널 하단에 「현재 링크는 이미 존재합니다」라는 빨간색 플로팅 알림이 표시됩니다.

4. 조준 버튼（Aim）

각 링크 오른쪽의 용 십자 조준 아이콘을 클릭하면 링크의 node-id를 분석해 해당 노드가 있는 페이지로 이동하고, 뷰포트를 자동으로 확대한 후 그 노드를 선택합니다. 링크가 다른 파일을 가리키는 경우(현재 열린 파일에서 노드를 찾을 수 없는 경우)「링크가 다른 파일을 가리킬 수 있습니다」라는 안내가 표시됩니다.

상태 표시

패널 오른쪽 위 상태 표시등은 작업에 따라 변합니다.

• 회색「작업 대기 중…」: 대기 상태

• 보라색「현재 AI 쓰기 중…」: 쓰기 작업 감지

• 초록색「현재 AI 읽기 중…」: 읽기 작업 감지

자동 롤백

매번 figma_run_js 실행 전에 문서 노드를 스냅샷 합니다. 실행 중 오류가 발생하면 새로 생성된 노드를 자동 삭제하고 롤백 수를 보고합니다. 기존 노드의 수정 사항은 자동 롤백되지 않습니다(다만 Figma의 Cmd/Ctrl+Z 실행 취소를 이용할 수 있습니다).

7. 보안

8. 환경 변수

9. 사용 가능한 helpers（figma_run_js 안에서 사용 가능）

figma_run_js는 다음을 주입합니다: figma(Figma API), args(구조화된 인자), helpers(안전한 헬퍼).

• helpers.loadFont(fontName)

• helpers.ensureTextFontEstolate(textNode, fallbackFontName)

• helpers.paint(value, theme) / helpers.hexToRgb(hex) / helpers.rgbToHex(rgb)

• helpers.normalizeHex(value, theme)

• helpers.findVariable(nameOrKey, resolvedType)

• helpers.indexDesignSystem(options)

• helpers.cloneReferenceNode(selector, options)

• helpers.importComponentByName(nameOrKey, options)

• helpers.applyTextStyle(textNode, styleName)

• helpers.applyPaintStyle(node, styleName, field)

• helpers.bindVariable(node, field, variableName, fallbackValue, resolvedType)

• helpers.bindFillVariable(node, variableName, fallbackValue) / helpers.bindStrokeVariable(...)

• helpers.findNodes(selector) / helpers.getNode(id)

• helpers.summarizeNode(node, depth) / helpers.inspectNodeAppearance(node)

• helpers.validateCanvas(options)

figma_run_js 코드 내에서는 옵셔널 체이닝 ?.과 널리시 ??를 피발 사용하는 것이 좋습니다. Figma 플러그인 런타임에서 거부될 수 있습니다.

11. 라이선스

MIT License.