Claude Talk to Figma MCP

<img src="images/claude-talk-to-figma.png" alt="Claude Talk to Figma collage" /> # 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](https://github.com/sonnylazuardi/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](https://claude.ai/download) or [Cursor](https://cursor.com/downloads) + [Figma Desktop](https://www.figma.com/downloads/) + [Bun](https://bun.sh) installed ### 2. 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. AI client configuration #### Option 1: DXT Package (Claude Desktop only) 1. **Download**: Get the latest `claude-talk-to-figma-mcp.dxt` from [releases](https://github.com/arinspunk/claude-talk-to-figma-mcp/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](images/cursor-config-1.png)) 3. Add this configuration: ```json { "mcpServers": { "ClaudeTalkToFigma": { "command": "bunx", "args": ["claude-talk-to-figma-mcp@latest"] } } } ``` 4. Save the file ([screenshot](images/cursor-config-2.png)) ### 4. Setup Figma Plugin (Required for all methods) Import `src/claude_mcp_plugin/manifest.json` in Figma → Menu → Plugins → Development ### 4. First Connection 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 ### 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 1. **Make Claude a UX expert**: [Use this prompt](prompts/prompt-ux-ui-specialist.md) 🎨 2. **Connect to your project**: "Talk to Figma, channel {channel-ID}" 3. **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: ```bash 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 ```bash bun run test # Run all tests bun run test:watch # Watch mode bun run test:coverage # Coverage report ``` ### Integration Testing ```bash 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 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 ### 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 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 - **[Taylor Smits](https://github.com/smitstay)** - DXT Package Support implementation, automated CI/CD workflows, testing improvements, and bug fixes ([PR #17](https://github.com/arinspunk/claude-talk-to-figma-mcp/pull/17), [PR #16](https://github.com/arinspunk/claude-talk-to-figma-mcp/pull/16), [PR #13](https://github.com/arinspunk/claude-talk-to-figma-mcp/pull/13), [PR #14](https://github.com/arinspunk/claude-talk-to-figma-mcp/pull/14)) - **[easyhak](https://github.com/easyhak)** - Fixed build script not working on Windows OS ([PR #10](https://github.com/arinspunk/claude-talk-to-figma-mcp/pull/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](https://github.com/smitstay) - [PR #17](https://github.com/arinspunk/claude-talk-to-figma-mcp/pull/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](CHANGELOG.md) for complete version history. --- ## 📄 License & Credits **License**: MIT License - see [LICENSE](LICENSE) file **Authors**: - **Xúlio Zé** - *Claude adaptation* - [GitHub](https://github.com/arinspunk) - **Sonny Lazuardi** - *Original implementation* - [GitHub](https://github.com/sonnylazuardi) **Acknowledgments**: - Anthropic team for Claude and Model Context Protocol - Figma community for excellent plugin API - Bun team for fast JavaScript runtime