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:

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:

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:

9. For text operations:

10. For converting legacy annotations:

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