Claude Talk to Figma MCP

A Model Context Protocol (MCP) plugin that allows Claude Desktop and other AI tools (GitHub Copilot, Cursor, etc.) to interact directly with Figma, enabling powerful AI-assisted design capabilities.

Important: This project is based on cursor-talk-to-figma-mcp by Sonny Lazuardi. It has been adapted to work with Claude Desktop and expanded with additional tools. Original credit belongs to Sonny Lazuardi ❤️

⚡ Installation

1. Prerequisites

Claude Desktop or Cursor + Figma Desktop + Bun installed

2. Setup

git clone https://github.com/arinspunk/claude-talk-to-figma-mcp.git
cd claude-talk-to-figma-mcp
bun install

macOS/Linux: bun run build
Windows: bun run build:win

3. AI client configuration

Option 1: DXT Package (Claude Desktop only)

Download: Get the latest claude-talk-to-figma-mcp.dxt from releases
Install: Double-click the .dxt file → Claude Desktop installs automatically

Option 2: JSON (Claude Desktop or Cursor)

Claude Desktop: Run bun run configure-claude (restart Claude Desktop)

Cursor:

Go to Cursor Settings → Tools & Integrations
Click "New MCP Server" to open mcp.json config (screenshot)
Add this configuration:

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

Save the file (screenshot)

4. Setup Figma Plugin (Required for all methods)

Import src/claude_mcp_plugin/manifest.json in Figma → Menu → Plugins → Development

4. First Connection

Start server: bun socket (verify at http://localhost:3055/status)
Connect plugin: Open Claude MCP Plugin in Figma → copy channel ID
Test: Ask your AI client: "Talk to Figma, channel {channel-ID}"

✅ Success: Your AI should confirm connection and you can start designing!

🚀 Core Concepts

How It Works

Claude Desktop ↔ MCP Server ↔ WebSocket Server ↔ Figma Plugin

Simple: Claude sends design commands → Figma executes them in real-time
Bidirectional: Get info from Figma, create/modify elements, manage components

Key Capabilities

Document Interaction: Analyze designs, get selections, export assets
Element Creation: Shapes, text, frames with full styling control
Smart Modifications: Colors, effects, auto-layout, responsive design
Text Mastery: Advanced typography, font loading, text scanning
Component Integration: Local and team library components

🛠️ Usage Patterns

Getting Started with AI Design

Make Claude a UX expert: Use this prompt 🎨
Connect to your project: "Talk to Figma, channel {channel-ID}"
Start designing: "Create a mobile app login screen with modern styling"

Effective Prompting Examples

✅ Good: "Create a dashboard with a sidebar navigation, header with user profile, and main content area with card-based metrics"

✅ Good: "Redesign this button component with hover states and better contrast ratios"

❌ Avoid: "Make it look nice" (too vague)

📚 Command Reference

📄 Document Tools

Command	Purpose	Example Use
`get_document_info`	Document analysis	Get project overview
`get_selection`	Current selection	What's selected now
`get_node_info`	Element details	Inspect specific component
`get_nodes_info`	Multiple elements info	Batch element inspection
`scan_text_nodes`	Find all text	Text audit and updates
`get_styles`	Document styles	Color/text style audit
`join_channel`	Connect to Figma	Establish communication
`export_node_as_image`	Asset export	Generate design assets

🔧 Creation Tools

Command	Purpose	Example Use
`create_rectangle`	Basic shapes	Buttons, backgrounds
`create_frame`	Layout containers	Page sections, cards
`create_text`	Text elements	Headlines, labels
`create_ellipse`	Circles/ovals	Profile pics, icons
`create_polygon`	Multi-sided shapes	Custom geometric elements
`create_star`	Star shapes	Decorative elements
`clone_node`	Duplicate elements	Copy existing designs
`group_nodes`	Organize elements	Component grouping
`ungroup_nodes`	Separate groups	Break apart components
`insert_child`	Nest elements	Hierarchical structure
`flatten_node`	Vector operations	Boolean operations

✏️ Modification Tools

Command	Purpose	Example Use
`set_fill_color`	Element colors	Brand color application
`set_stroke_color`	Border colors	Outline styling
`move_node`	Positioning	Layout adjustments
`resize_node`	Size changes	Responsive scaling
`delete_node`	Remove elements	Clean up designs
`set_corner_radius`	Rounded corners	Modern UI styling
`set_auto_layout`	Flexbox-like layout	Component spacing
`set_effects`	Shadows/blurs	Visual polish
`set_effect_style_id`	Apply effect styles	Consistent shadow styles

📝 Text Tools

Command	Purpose	Example Use
`set_text_content`	Text updates	Copy changes
`set_multiple_text_contents`	Batch text updates	Multi-element editing
`set_font_name`	Typography	Brand font application
`set_font_size`	Text sizing	Hierarchy creation
`set_font_weight`	Text weight	Bold/light variations
`set_letter_spacing`	Character spacing	Typography fine-tuning
`set_line_height`	Vertical spacing	Text readability
`set_paragraph_spacing`	Paragraph gaps	Content structure
`set_text_case`	Case transformation	UPPER/lower/Title case
`set_text_decoration`	Text styling	Underline/strikethrough
`get_styled_text_segments`	Text analysis	Rich text inspection
`load_font_async`	Font loading	Custom font access

🎨 Component Tools

Command	Purpose	Example Use
`get_local_components`	Project components	Design system audit
`get_remote_components`	Team libraries	Shared component access
`create_component_instance`	Use components	Consistent UI elements

Building DXT Package (Developers)

To create your own DXT package:

npm run build:dxt    # Builds TypeScript and packages DXT

This creates claude-talk-to-figma-mcp.dxt ready for distribution.

🧪 Testing & Quality Assurance

Automated Testing

bun run test            # Run all tests
bun run test:watch      # Watch mode
bun run test:coverage   # Coverage report

Integration Testing

bun run test:integration  # Guided end-to-end testing

Manual Verification Checklist

WebSocket server starts on port 3055
Figma plugin connects and generates channel ID
AI tool recognizes "ClaudeTalkToFigma" MCP (Claude Desktop, Cursor, etc.)
Basic commands execute (create rectangle, change color)
Error handling works (invalid commands, timeouts)
Channel communication works between AI tool and Figma

🐛 Troubleshooting & Support

Connection Issues

"Can't connect to WebSocket": Ensure bun socket is running
"Plugin not found": Verify plugin import in Figma Development settings
"MCP not available":
- Claude Desktop: Run bun run configure-claude and restart Claude
- Cursor IDE: Check MCP configuration in mcp.json file
- Other AI tools: Verify MCP integration settings

Execution Problems

"Command failed": Check Figma development console for errors
"Font not found": Use load_font_async to verify font availability
"Permission denied": Ensure you have edit access to the Figma document
"Timeout errors": Complex operations may need retry

Performance Issues

Slow responses: Large documents may require more processing time
Memory usage: Close unused Figma tabs, restart if necessary
WebSocket disconnects: Server auto-reconnects, restart if persistent

Common Solutions

Restart sequence: Stop server → Close AI tool → Restart both
Clean reinstall: Delete node_modules → bun install → bun run build
Check logs: Server terminal shows detailed error messages
Update fonts: Some team fonts require manual loading in Figma
Configuration check: Verify MCP setup in your AI tool's settings
Port conflicts: Ensure port 3055 is not used by other applications

🏗️ Advanced Topics

Architecture Deep Dive

+----------------+     +-------+     +---------------+     +---------------+
|                |     |       |     |               |     |               |
| Claude Desktop |<--->|  MCP  |<--->| WebSocket Srv |<--->| Figma Plugin  |
|   (AI Agent)   |     |       |     |  (Port 3055)  |     |  (UI Plugin)  |
|                |     |       |     |               |     |               |
+----------------+     +-------+     +---------------+     +---------------+

Design Principles:

MCP Server: Business logic, validation, default values
WebSocket Server: Message routing and protocol translation
Figma Plugin: Pure command executor in Figma context

Benefits:

Clear separation of concerns
Easy testing and maintenance
Scalable architecture for additional tools

Project Structure

src/
  talk_to_figma_mcp/     # MCP Server implementation
    server.ts            # Main entry point
    tools/               # Tool categories by function
      document-tools.ts  # Document interaction
      creation-tools.ts  # Shape and element creation
      modification-tools.ts # Property modification
      text-tools.ts      # Text manipulation
    utils/               # Shared utilities
    types/               # TypeScript definitions
  claude_mcp_plugin/     # Figma plugin
    code.js              # Plugin implementation
    manifest.json        # Plugin configuration

Contributing Guidelines

Fork and Branch: git checkout -b feature/amazing-feature
Code Standards: Follow existing TypeScript patterns
Testing: Add tests for new functionality
Documentation: Update relevant sections
Pull Request: Clear description of changes

Recent Contributors

Taylor Smits - DXT Package Support implementation, automated CI/CD workflows, testing improvements, and bug fixes (PR #17, PR #16, PR #13, PR #14)
easyhak - Fixed build script not working on Windows OS (PR #10)

📋 Version History

Current: 0.6.1

🔧 Tool Fix: The set_stroke_color tool now correctly accepts a strokeWeight of 0 for creating invisible strokes.

Previous: 0.6.0

🚀 DXT Package Support: one-click installation via Claude Desktop's extension manager (Thanks to Taylor Smits - PR #17)
📦 Automated Distribution: GitHub Actions workflow for automatic DXT package generation and release uploads
⚡ Enhanced UX: Installation time reduced from 15-30 minutes to 2-5 minutes for end users
🔧 Developer Tools: New build scripts for DXT packaging (npm run build:dxt, npm run pack)

See CHANGELOG.md for complete version history.

📄 License & Credits

License: MIT License - see LICENSE file

Authors:

Xúlio Zé - Claude adaptation - GitHub
Sonny Lazuardi - Original implementation - GitHub

Acknowledgments:

Anthropic team for Claude and Model Context Protocol
Figma community for excellent plugin API
Bun team for fast JavaScript runtime