Cursor Talk to Figma MCP 연결 문제 해결 가이드

문제 상황

Cursor의 Tools & MCP 설정에서 TalkToFigma MCP 서버가 빨간 점(연결 실패) 상태로 표시되는 문제가 발생했습니다.

증상

• Figma 플러그인과 WebSocket 서버(port 3055)는 정상 연결됨
• Cursor가 WebSocket 연결은 감지하지만 MCP 서버 자체는 시작되지 않음
• AI Agent에게 Figma 작업을 명령해도 실행되지 않음

원인 분석

1. WebSocket vs MCP 서버의 차이

• WebSocket 서버: Figma 플러그인 ↔ WebSocket 서버 간 통신 (정상 작동)
• MCP 서버: Cursor ↔ MCP 서버 간 통신 (연결 실패)

이 두 개는 별개의 프로세스입니다.

2. 실제 문제 원인

mcp.json에서 다음과 같이 설정되어 있었습니다:

{
  "mcpServers": {
    "TalkToFigma": {
      "command": "bunx",
      "args": ["cursor-talk-to-figma-mcp@latest"]
    }
  }
}

하지만 실제로는:

1. 패키지가 npm registry에 공개되지 않음: bunx cursor-talk-to-figma-mcp@latest 명령어가 작동하지 않음
2. 로컬 개발 버전 사용 필요: 다운로드한 프로젝트를 직접 빌드하고 실행해야 함
3. Node.js 미설치: package.json의 bin 설정이 node를 기본으로 사용하는데 시스템에 설치되지 않음

해결 방법

1단계: 프로젝트 빌드

cd ~/Downloads/cursor-talk-to-figma-mcp-main
bun run build

빌드 후 dist/ 폴더에 다음 파일들이 생성됩니다:

• server.js (ES Module)
• server.cjs (CommonJS)

2단계: mcp.json 수정

Cursor의 MCP 설정 파일을 수정합니다:

파일 경로: Cursor Settings → Tools & MCP → Edit Config

{
  "mcpServers": {
    "TalkToFigma": {
      "command": "bun",
      "args": [
        "run",
        "/Users/ywangnon/Downloads/cursor-talk-to-figma-mcp-main/dist/server.js"
      ],
      "env": {
        "FIGMA_CHANNEL": "egkdlok5"
      }
    }
  }
}

3단계: Cursor 재시작

1. Cursor 완전 종료 (Cmd + Q)
2. 다시 시작
3. Settings → Tools & MCP에서 초록 점 확인 ✅

mcp.json 설정 상세 설명

{
  "mcpServers": {
    // MCP 서버 목록을 정의하는 객체

    "TalkToFigma": {
      // 서버 식별자 (Cursor UI와 명령어에서 사용되는 이름)

      "command": "bun",
      // 실행할 명령어
      // - "node": Node.js로 실행
      // - "bun": Bun 런타임으로 실행
      // - "bunx": npx처럼 패키지를 다운로드하고 실행
      // - 절대 경로: 특정 실행 파일 지정

      "args": [
        "run",
        "/Users/ywangnon/Downloads/cursor-talk-to-figma-mcp-main/dist/server.js"
      ],
      // command에 전달할 인자들 (배열)
      // "bun run <파일경로>" 형태로 실행됨
      // 반드시 절대 경로를 사용해야 함

      "env": {
        // 환경 변수 설정 (key-value 형태)

        "FIGMA_CHANNEL": "egkdlok5"
        // Figma 플러그인과 MCP 서버가 통신할 WebSocket 채널 ID
        // Figma 플러그인에서 생성된 고유 채널과 일치해야 함
        // 플러그인 UI에서 "Connected to server on port 3055 in channel: egkdlok5" 확인
      }
    }
  }
}

각 필드의 역할

필드	설명	예시
command	MCP 서버를 실행할 런타임 또는 명령어	"bun", "node", "python"
args	command에 전달할 인자 배열	["run", "/path/to/server.js"]
env	서버에 전달할 환경 변수	{"FIGMA_CHANNEL": "egkdlok5"}

환경 변수 추가 예시

필요에 따라 더 많은 환경 변수를 추가할 수 있습니다:

"env": {
  "FIGMA_CHANNEL": "egkdlok5",
  "WEBSOCKET_URL": "ws://localhost:3055",
  "NODE_ENV": "production",
  "LOG_LEVEL": "debug"
}

채널 ID 변경 시 대응

Figma 플러그인을 재시작하면 새로운 채널 ID가 생성됩니다.

1. Figma 플러그인에서 새 채널 확인

Connected to server on port 3055 in channel: **새로운채널ID**

2. mcp.json 업데이트

"env": {
  "FIGMA_CHANNEL": "새로운채널ID"
}

3. Cursor 재시작

추가 팁

WebSocket 서버 시작

MCP 서버와는 별도로 WebSocket 서버도 실행되어야 합니다:

cd ~/Downloads/cursor-talk-to-figma-mcp-main
bun socket

출력 예시:

WebSocket server running on port 3055
New client connected
Received message from client: {"type":"join","channel":"egkdlok5"}

실행 순서

1. WebSocket 서버 시작: bun socket
2. Figma 플러그인 실행: Figma에서 플러그인 시작
3. Cursor MCP 서버: mcp.json 설정 후 Cursor 재시작

디버깅 방법

MCP 서버가 제대로 실행되는지 테스트

bun run /Users/ywangnon/Downloads/cursor-talk-to-figma-mcp-main/dist/server.js

Cursor 로그 확인

tail -f ~/Library/Logs/Cursor/main.log

참고 사항

• MCP는 stdio(표준 입출력) 를 통해 통신합니다
• 서버는 JSON-RPC 형식의 메시지를 주고받습니다
• Cursor는 MCP 서버를 자동으로 시작하고 관리합니다
• 빨간 점은 서버 프로세스 시작 실패를 의미합니다
• 초록 점은 정상적으로 연결되어 도구(tools)를 사용할 수 있는 상태입니다

사용 예시

Cursor AI Agent에서 다음과 같이 명령할 수 있습니다:

@TalkToFigma Figma에 100x100 크기의 빨간색 사각형을 생성해줘

또는:

Use the TalkToFigma MCP tools to create a rectangle in Figma

---

작성일: 2025년 10월 7일
환경: macOS, Bun 1.x, Cursor Editor