Cursor Talk to Figma MCP Setup Guide for AI Agents.

CURSOR_FIGMA_MCP_SETUP_GUIDE.md

Cursor Talk to Figma MCP Setup Guide for AI Agents

🎯 Objective

Install and configure Cursor-Figma MCP integration with fail-safe checkpoints at each step.

📋 Prerequisites Check

Execute these commands and verify all pass before proceeding:

# Check 1: Cursor IDE installed
which cursor && echo "✅ Cursor found" || echo "❌ ERROR: Install Cursor IDE first"

# Check 2: Git available  
git --version && echo "✅ Git found" || echo "❌ ERROR: Git not available"

# Check 3: macOS verification
sw_vers -productVersion && echo "✅ macOS confirmed" || echo "❌ ERROR: macOS required"

CHECKPOINT: All three checks must show ✅ before proceeding.

---

🚀 Installation Steps

Step 1: Install Bun Runtime

# Install Bun
curl -fsSL https://bun.sh/install | bash

# Reload shell environment
source ~/.zshrc 2>/dev/null || source ~/.bashrc 2>/dev/null || true

# Verify installation
bun --version && echo "✅ Bun installed successfully" || echo "❌ ERROR: Bun installation failed"

CHECKPOINT: Must see Bun version number. If failed, stop here and troubleshoot.

Step 2: Clone and Setup Project

# Navigate to Sites directory (create if doesn't exist)
mkdir -p ~/Sites && cd ~/Sites

# Clone repository
git clone https://github.com/sonnylazuardi/cursor-talk-to-figma-mcp.git

# Enter project directory
cd cursor-talk-to-figma-mcp

# Verify project structure
ls package.json src && echo "✅ Project structure valid" || echo "❌ ERROR: Invalid project structure"

CHECKPOINT: Must see ✅ Project structure valid. Current directory must be cursor-talk-to-figma-mcp.

Step 3: Build and Configure

# Install dependencies
bun install && echo "✅ Dependencies installed" || echo "❌ ERROR: Dependency installation failed"

# Build project
bun run build && echo "✅ Build successful" || echo "❌ ERROR: Build failed"

# Verify build output
test -f dist/server.js && echo "✅ Server built" || echo "❌ ERROR: Server build missing"

# Setup MCP configuration
bun setup && echo "✅ MCP setup complete" || echo "❌ ERROR: MCP setup failed"

# Verify MCP config
test -f .cursor/mcp.json && echo "✅ MCP config created" || echo "❌ ERROR: MCP config missing"

CHECKPOINT: All four steps must show ✅. The file .cursor/mcp.json must exist in current directory.

Step 4: Launch Cursor with MCP

🚨 CRITICAL: Cursor must be launched from the project directory to load MCP configuration.

# Verify current directory is correct
pwd | grep "cursor-talk-to-figma-mcp" && echo "✅ Correct directory" || echo "❌ ERROR: Wrong directory"

# Launch Cursor from project directory
cursor .

# Wait for initialization
sleep 15

CHECKPOINT: Cursor should open with the project loaded. Verify in Cursor:

1. Open Settings (Cmd+,)
2. Search "MCP"
3. Confirm "TalkToFigma" shows as "Connected"

Step 5: Start WebSocket Server

🔄 NEW TERMINAL REQUIRED: Open a completely new terminal window and run:

# Navigate to project directory
cd ~/Sites/cursor-talk-to-figma-mcp

# Start WebSocket server (keep this running)
bun socket

CHECKPOINT: Server should start and show "WebSocket server running on port 3001" or similar message. Keep this terminal open and running.

---

🎯 Final Setup (Quick Guide)

Step 6: Install Figma Plugin

Choose ONE method and install:

• Community Plugin: https://www.figma.com/community/plugin/1485687494525374295/cursor-talk-to-figma-mcp-plugin
• Local Plugin: In Figma > Plugins > Development > New Plugin > Link existing plugin > Select ~/Sites/cursor-talk-to-figma-mcp/src/cursor_mcp_plugin/manifest.json

Step 7: Test Everything Works

In Cursor (where MCP is connected):

1. Test MCP: join_channel → Should see "Successfully joined channel"
2. Test Figma: get_document_info → Should see JSON data from Figma

✅ If both commands work, setup is complete!

---

⚠️ Troubleshooting

Issue: MCP Not Connected

# Check directory
pwd | grep "cursor-talk-to-figma-mcp" || echo "Navigate to project directory first"

# Restart Cursor from project directory  
cd ~/Sites/cursor-talk-to-figma-mcp && cursor .

Issue: WebSocket Connection Failed

# Check if server is running
lsof -i :3001 || echo "Start WebSocket server: bun socket"

# Restart server
cd ~/Sites/cursor-talk-to-figma-mcp && bun socket

Issue: Figma Plugin Not Working

• Ensure plugin is activated in Figma
• Check WebSocket server is running
• Restart Figma if needed

---

✅ Success Verification

Installation is complete when ALL of the following are true:

1. pwd shows you're in cursor-talk-to-figma-mcp directory
2. test -f .cursor/mcp.json returns success
3. Cursor Settings shows "TalkToFigma" as "Connected"
4. join_channel command works in Cursor
5. get_document_info returns Figma data
6. WebSocket server shows active connections

If any verification fails, repeat the corresponding step above.