figma-copilot

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 integration
• src/figma_copilot_plugin/ - Figma plugin for communicating with MCP clients
• src/socket.ts - WebSocket server that facilitates communication between the MCP server and Figma plugin

Get Started

1. Install Bun if you haven't already:

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

2. Run setup to configure MCP

bun setup

3. Start the Websocket server

bun socket

4. MCP server

bunx figma-copilot

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

1. In Figma, go to Plugins > Development > New Plugin
2. Choose "Link existing plugin"
3. Select the src/figma_copilot_plugin/manifest.json file
4. The plugin should now be available in your Figma development plugins

Windows + WSL Guide

1. Install bun via powershell

powershell -c "irm bun.sh/install.ps1|iex"

2. Uncomment the hostname 0.0.0.0 in src/socket.ts

// uncomment this to allow connections in windows wsl
hostname: "0.0.0.0",

3. Start the websocket

bun socket

Usage

1. Start the WebSocket server
2. Install the MCP server in your MCP client
3. Open Figma and run the Figma Copilot Plugin
4. Connect the plugin to the WebSocket server by joining a channel using join_channel
5. 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 document
• get_current_context - Get comprehensive context including selection, focused slide (if in Slides mode), and optionally document info
• get_selection - DEPRECATED: Use get_current_context instead
• read_my_design - Get detailed node information about the current selection without parameters
• get_nodes - Get detailed information about one or more nodes (accepts single ID or array)
• get_node_info - DEPRECATED: Use get_nodes with single node ID instead
• get_nodes_info - DEPRECATED: Use get_nodes with array of node IDs instead
• get_focused_slide - DEPRECATED: Use get_current_context with includeSlideDetails option
• get_slides_mode - DEPRECATED: Use get_current_context with includeSlideDetails option

Annotations

• get_annotations - Get all annotations in the current document or specific node
• set_annotation - Create or update an annotation with markdown support
• set_multiple_annotations - Batch create/update multiple annotations efficiently
• scan_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 animation
• set_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 name
• create_frame - Create a new frame with position, size, and optional name
• create_text - Create a new text node with customizable font properties

Text Operations

Basic Text Operations

• scan_text_nodes - DEPRECATED: Use scan_nodes_with_options with nodeTypes: ['TEXT'] instead
• scan_nodes_with_options - Enhanced scanning with depth control, timeout handling, and partial results
• set_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 portions
• set_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 ranges
• get_text_style_range - Get text styling for a specific range
• set_text_decoration_range - Set advanced text decoration properties
• get_text_decoration_range - Get text decoration properties for a range
• set_range_font - Change font family and style for a text range
• set_range_font_size - Change font size for a text range
• set_range_fills - Set text color for a specific range
• get_styled_text_segments - Get detailed information about text segments and their properties
• set_component_description - Set component description using Markdown
• get_component_description - Get component description in Markdown format
• normalize_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 frames
• set_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 node
• set_corner_radius - Set the corner radius of a node with optional per-corner control

Layout & Organization

• move_node - Move a node to a new position
• resize_node - Resize a node with new dimensions
• delete_node - Delete a node
• delete_multiple_nodes - Delete multiple nodes at once efficiently
• clone_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_info - DEPRECATED: Use get_nodes with array of node IDs instead
• set_multiple_nodes_property - Set the same property value on multiple nodes at once
• execute_batch - Execute multiple different commands in sequence with a single round-trip
• get_connection_status - Get current connection status and statistics

Components & Styles

• get_styles - Get information about local styles
• get_local_components - Get information about local components
• create_component_instance - Create an instance of a component
• get_instance_overrides - Extract override properties from a selected component instance
• set_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 points
• get_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 designs
• read_design_strategy - Best practices for reading Figma designs
• text_replacement_strategy - Systematic approach for replacing text in Figma designs
• annotation_conversion_strategy - Strategy for converting manual annotations to Figma's native annotations
• swap_overrides_instances - Strategy for transferring overrides between component instances in Figma
• reaction_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 sequence
• batch_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

1. Navigate to the Figma plugin directory:

   cd src/figma_copilot_plugin
   

2. Edit code.js and ui.html

Best Practices

When working with the Figma MCP:

1. Always join a channel before sending commands
2. Get document overview using get_document_info first
3. Check current context with get_current_context before modifications
4. Use appropriate creation tools based on needs:
   • create_frame for containers
   • create_rectangle for basic shapes
   • create_text for text elements
5. Verify changes using get_node_info
6. Use component instances when possible for consistency
7. Handle errors appropriately as all commands can throw exceptions
8. For large designs:
   • Use scan_nodes_with_options with appropriate timeout and depth settings
   • Monitor progress through WebSocket updates
   • Implement appropriate error handling
9. For text operations:
   • Use batch operations when possible
   • Consider structural relationships
   • Verify changes with targeted exports
10. For converting legacy annotations:
    • Scan text nodes to identify numbered markers and descriptions
    • Use scan_nodes_by_types to 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_annotations in batches
    • Verify all annotations are properly linked to their targets
    • Delete legacy annotation nodes after successful conversion
11. Visualize prototype noodles as FigJam connectors:

• Use get_reactions to extract prototype flows,
• set a default connector with set_default_connector,
• and generate connector lines with create_connections for 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