Figma Copilot
A Model Context Protocol (MCP) server that enables AI assistants to interact with Figma designs programmatically. Compatible with any MCP client including Cursor, Claude Desktop, and other MCP-enabled applications. Features advanced text handling, batch operations, and comprehensive design automation capabilities.
Credits
This project is based on cursor-talk-to-figma-mcp by Sonny Lazuardi.
Disclaimer
This is an independent project and is not affiliated with, officially maintained, authorized, endorsed, or sponsored by Figma, Inc. All product and company names are trademarks™ or registered® trademarks of their respective holders.
Key Enhancements
v0.3.2 (Latest)
- Text Formatting Preservation - Text updates no longer lose formatting (bold, italic, colors, fonts). See Enhanced Text Operations Guide.
- Batch Operations - 50-90% performance improvement for bulk operations. See Batch Operations Guide.
- Enhanced Error Handling - Specific, actionable error messages with suggestions
- Timeout Solutions - New scanning options with depth control and partial results
- Smart Text Operations - Find/replace with formatting preservation
Previous Enhancements
- Fixed "Cannot unwrap symbol" error when working with mixed fonts. See Font Handling Documentation.
- Improved font loading with
getRangeAllFontNames()API - Better error handling with
Promise.allSettled()for font loading - Safe value returns to avoid serialization issues
- Enhanced logging for debugging font issues
Project Structure
src/talk_to_figma_mcp/- TypeScript MCP server for Figma integrationsrc/figma_copilot_plugin/- Figma plugin for communicating with MCP clientssrc/socket.ts- WebSocket server that facilitates communication between the MCP server and Figma plugin
Get Started
- Install Bun if you haven't already:
curl -fsSL https://bun.sh/install | bash
- Run setup to configure MCP
bun setup
- Start the Websocket server
bun socket
- MCP server
bunx figma-copilot
- NEW Install Figma plugin from Figma community page or install locally
Quick Start Guide
Video tutorials coming soon!
Design Automation Example
Bulk text content replacement
Thanks to @dusskapark for contributing the bulk text replacement feature.
Instance Override Propagation Another contribution from @dusskapark Propagate component instance overrides from a source instance to multiple target instances with a single command. This feature dramatically reduces repetitive design work when working with component instances that need similar customizations.
Performance Improvements (v0.3.2)
Based on real production usage with bulk infographic creation:
| Operation | Before v0.3.2 | After v0.3.2 | Improvement |
|---|---|---|---|
| Clone 20 nodes | 50 seconds | 5 seconds | 90% faster |
| Update 112 text nodes | 15 minutes | 30 seconds | 96% faster |
| Scan large document | Timeout after 30s | 3 seconds | No timeouts |
| Text + formatting update | 2 separate calls | 1 combined call | 50% fewer API calls |
Manual Setup and Installation
MCP Server: Integration with MCP Clients
Add the server to your MCP client configuration. For example, in Cursor's ~/.cursor/mcp.json or Claude Desktop's configuration:
{
"mcpServers": {
"figma-copilot": {
"command": "bunx",
"args": ["figma-copilot@latest"]
}
}
}
WebSocket Server
Start the WebSocket server:
bun socket
Figma Plugin
- In Figma, go to Plugins > Development > New Plugin
- Choose "Link existing plugin"
- Select the
src/figma_copilot_plugin/manifest.jsonfile - The plugin should now be available in your Figma development plugins
Windows + WSL Guide
- Install bun via powershell
powershell -c "irm bun.sh/install.ps1|iex"
- Uncomment the hostname
0.0.0.0insrc/socket.ts
// uncomment this to allow connections in windows wsl
hostname: "0.0.0.0",
- Start the websocket
bun socket
Usage
- Start the WebSocket server
- Install the MCP server in your MCP client
- Open Figma and run the Figma Copilot Plugin
- Connect the plugin to the WebSocket server by joining a channel using
join_channel - Use your MCP client to communicate with Figma using the MCP tools
MCP Tools
The MCP server provides the following tools for interacting with Figma:
Document & Selection
get_document_info- Get information about the current Figma documentget_current_context- Get comprehensive context including selection, focused slide (if in Slides mode), and optionally document infoget_selectionget_current_contextinsteadread_my_design- Get detailed node information about the current selection without parametersget_nodes- Get detailed information about one or more nodes (accepts single ID or array)get_node_infoget_nodeswith single node ID insteadget_nodes_infoget_nodeswith array of node IDs insteadget_focused_slideget_current_contextwith includeSlideDetails optionget_slides_modeget_current_contextwith includeSlideDetails option
Annotations
get_annotations- Get all annotations in the current document or specific nodeset_annotation- Create or update an annotation with markdown supportset_multiple_annotations- Batch create/update multiple annotations efficientlyscan_nodes_by_types- Scan for nodes with specific types (useful for finding annotation targets)
Prototyping & Connections
get_reactions- Get all prototype reactions from nodes with visual highlight animationset_default_connector- Set a copied FigJam connector as the default connector style for creating connections (must be set before creating connections)create_connections- Create FigJam connector lines between nodes, based on prototype flows or custom mapping
Creating Elements
create_rectangle- Create a new rectangle with position, size, and optional namecreate_frame- Create a new frame with position, size, and optional namecreate_text- Create a new text node with customizable font properties
Text Operations
Basic Text Operations
scan_text_nodesscan_nodes_with_optionswithnodeTypes: ['TEXT']insteadscan_nodes_with_options- Enhanced scanning with depth control, timeout handling, and partial resultsset_text_content- Set the text content of a single text node (Note: loses formatting)set_multiple_text_contents- Batch update multiple text nodes efficiently (Note: loses formatting)
Text with Formatting Preservation (v0.3.2)
See Enhanced Text Operations Guide for an overview.
update_text_preserve_formatting- Update text while preserving all character formatting (bold, italic, colors, fonts)smart_text_replace- Find and replace text while preserving formatting of unchanged portionsset_multiple_text_contents_with_styles- Batch update text with formatting in a single operation
Text Styling
See Text Styling Guide for detailed usage.
set_text_style_range- Apply text styling (bold, italic, underline, strikethrough) to specific character rangesget_text_style_range- Get text styling for a specific rangeset_text_decoration_range- Set advanced text decoration propertiesget_text_decoration_range- Get text decoration properties for a rangeset_range_font- Change font family and style for a text rangeset_range_font_size- Change font size for a text rangeset_range_fills- Set text color for a specific rangeget_styled_text_segments- Get detailed information about text segments and their propertiesset_component_description- Set component description using Markdownget_component_description- Get component description in Markdown formatnormalize_markdown- Normalize Markdown text to Figma's supported subset
Auto Layout & Spacing
set_layout_mode- Set the layout mode and wrap behavior of a frame (NONE, HORIZONTAL, VERTICAL)set_padding- Set padding values for an auto-layout frame (top, right, bottom, left)set_axis_align- Set primary and counter axis alignment for auto-layout framesset_layout_sizing- Set horizontal and vertical sizing modes for auto-layout frames (FIXED, HUG, FILL)set_item_spacing- Set distance between children in an auto-layout frame
Styling
set_fill_color- Set the fill color of a node (RGBA)set_stroke_color- Set the stroke color and weight of a nodeset_corner_radius- Set the corner radius of a node with optional per-corner control
Layout & Organization
move_node- Move a node to a new positionresize_node- Resize a node with new dimensionsdelete_node- Delete a nodedelete_multiple_nodes- Delete multiple nodes at once efficientlyclone_node- Create a copy of an existing node with optional position offset
Batch Operations (v0.3.2)
See Batch Operations Guide for best practices.
clone_multiple_nodes- Clone a node to multiple positions in one operation (50-90% faster than individual clones)get_multiple_nodes_infoget_nodeswith array of node IDs insteadset_multiple_nodes_property- Set the same property value on multiple nodes at onceexecute_batch- Execute multiple different commands in sequence with a single round-tripget_connection_status- Get current connection status and statistics
Components & Styles
get_styles- Get information about local stylesget_local_components- Get information about local componentscreate_component_instance- Create an instance of a componentget_instance_overrides- Extract override properties from a selected component instanceset_instance_overrides- Apply extracted overrides to target instances
Composite Tools
extract_slide_content- Extract all content from a Figma slide including text, tables, and optionally images (supports raw or structured output)get_presentation_summary- Generate an overview of a Figma presentation including slide count, slide titles, and optionally an outline summarizing key pointsget_table_data- Extract data from a Figma table node in various formats (array, object, or CSV) with customizable header handling
Export & Advanced
export_node_as_image- Export a node as an image (PNG, JPG, SVG, or PDF) - limited support on image currently returning base64 as text
Connection Management
join_channel- Join a specific channel to communicate with Figma
MCP Prompts
The MCP server includes several helper prompts to guide you through complex design tasks:
design_strategy- Best practices for working with Figma designsread_design_strategy- Best practices for reading Figma designstext_replacement_strategy- Systematic approach for replacing text in Figma designsannotation_conversion_strategy- Strategy for converting manual annotations to Figma's native annotationsswap_overrides_instances- Strategy for transferring overrides between component instances in Figmareaction_to_connector_strategy- Strategy for converting Figma prototype reactions to connector lines using the output of 'get_reactions', and guiding the use 'create_connections' in sequencebatch_operations_guide- Best practices for efficient bulk operations in Figma (v0.3.2)error_recovery_guide- How to handle common errors and timeouts in Figma operations (v0.3.2)text_formatting_guide- Best practices for updating text while preserving formatting (v0.3.2)
Development
Building the Figma Plugin
-
Navigate to the Figma plugin directory:
cd src/figma_copilot_plugin -
Edit code.js and ui.html
Best Practices
When working with the Figma MCP:
- Always join a channel before sending commands
- Get document overview using
get_document_infofirst - Check current context with
get_current_contextbefore modifications - Use appropriate creation tools based on needs:
create_framefor containerscreate_rectanglefor basic shapescreate_textfor text elements
- Verify changes using
get_node_info - Use component instances when possible for consistency
- Handle errors appropriately as all commands can throw exceptions
- For large designs:
- Use
scan_nodes_with_optionswith appropriate timeout and depth settings - Monitor progress through WebSocket updates
- Implement appropriate error handling
- Use
- For text operations:
- Use batch operations when possible
- Consider structural relationships
- Verify changes with targeted exports
- For converting legacy annotations:
- Scan text nodes to identify numbered markers and descriptions
- Use
scan_nodes_by_typesto find UI elements that annotations refer to - Match markers with their target elements using path, name, or proximity
- Categorize annotations appropriately with
get_annotations - Create native annotations with
set_multiple_annotationsin batches - Verify all annotations are properly linked to their targets
- Delete legacy annotation nodes after successful conversion
- Visualize prototype noodles as FigJam connectors:
- Use
get_reactionsto extract prototype flows, - set a default connector with
set_default_connector, - and generate connector lines with
create_connectionsfor clear visual flow mapping.
Troubleshooting
Font Issues
If you encounter "Cannot unwrap symbol" errors when updating text, this is likely due to mixed fonts in text nodes. See Font Handling Documentation for details on how the plugin handles mixed fonts and available strategies.
Timeout Issues
For large documents that cause timeouts, use scan_nodes_with_options with depth limiting and partial results. See Batch Operations Guide for optimization strategies.
Documentation
- Batch Operations Guide - Learn how to use batch operations for massive performance gains
- Enhanced Text Operations Guide - Preserve formatting while updating text
- Text Styling Guide - Apply and manage text styles
- Font Handling Documentation - Handle mixed fonts and font loading strategies
- Changelog v0.3.2 - Latest release notes
License
MIT