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

$3

- Claude Desktop or Cursor + Figma Desktop

$3

#### The Pro Way 🚀
If you already have Node.js installed, you can just run:
``bash
npx claude-talk-to-figma-mcp
`
This single command will clone the repository, install optimized dependencies (Bun), and start the socket server for you automatically.

#### Manual Way 🛠️
Use this if you prefer a manual setup:
`bash
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

#### Option 1: DXT Package (Claude Desktop only)
1. Download: Get the latest claude-talk-to-figma-mcp.dxt from releases
2. 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:
1. Go to Cursor Settings → Tools & Integrations
2. Click "New MCP Server" to open mcp.json config (screenshot)
3. Add this configuration:
`json
{
"mcpServers": {
"ClaudeTalkToFigma": {
"command": "bunx",
"args": ["claude-talk-to-figma-mcp@latest"]
}
}
}
`
4. Save the file (screenshot)

$3


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

$3

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

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

---

🚀 Core Concepts

$3

`
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

$3

- 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

$3

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

$3

`
✅ 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

$3


| 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 |

$3

| 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 |

$3

| 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 |

$3

| 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 |

$3

| 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 |

---

$3

To create your own DXT package:
`bash
npm run build:dxt # Builds TypeScript and packages DXT
`
This creates claude-talk-to-figma-mcp.dxt ready for distribution.

---

🧪 Testing & Quality Assurance

$3


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

$3

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

$3

- [ ] 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

$3

- "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

$3

- "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

$3

- 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

$3

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

---

🏗️ Advanced Topics

$3

`
+----------------+ +-------+ +---------------+ +---------------+
| | | | | | | |
| 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

$3


`
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
`

$3

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

#### Recent Contributors
- Rob Dearborn - Optimized component lookup to resolve timeout issues and implemented set_text_style_id tool (PR #42, PR #43)
- sk (kovalevsky) - Fixed SVG export format parameters and added comprehensive page management tools (create_page, delete_page, rename_page, get_pages, set_current_page) (PR #32)
- Beomsu Koh - Added rename_node tool for better organization of Figma elements (PR #36)
- Timur - Improved Zod validation for join_channel parameter (PR #29)
- 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

$3


- 🚀 One-command Setup: Unified launcher via npx claude-talk-to-figma-mcp for frictionless installation.
- 🛠️ Smart Environment: Automated Bun detection and OS-specific setup prompts.
- 🛡️ CI/CD Stability: Fixed TypeScript definitions and release permissions for faster delivery.

$3

- 🎨 New Tools: Added set_text_style_id, rename_node, and full suite of Page Management tools.
- 🔧 Tool Fix: The set_stroke_color tool now correctly accepts a strokeWeight of 0 for creating invisible strokes.
- 🚀 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