Figma Sparrow MCP Server

What is this?

Figma Sparrow MCP connects AI assistants (like Claude) to Figma, enabling:

🐛 Plugin debugging - Capture console logs, errors, and stack traces
📸 Visual debugging - Take screenshots for context
🎨 Design system extraction - Pull variables, components, and styles
✏️ Design creation - Create UI components, frames, and layouts directly in Figma
🔧 Variable management - Create, update, rename, and delete design tokens
⚡ Real-time monitoring - Watch logs as plugins execute
🔄 Local Git install - Clone the repo and run locally for full control

⚡ Quick Start

For Contributors: Local Git Mode

Best for: Developers who want to modify source code or contribute to the project.

What you get: Full toolset plus source code access.

Quick Setup

# Clone and build
git clone https://github.com/TrueSparrowSystems/figma-sparrow-mcp.git
cd figma-sparrow-mcp
npm install
npm run build:local

Configure Your MCP Client

Add to your config file:

{
  "mcpServers": {
    "figma-sparrow": {
      "command": "node",
      "args": ["/absolute/path/to/figma-sparrow-mcp/dist/local.js"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "figd_YOUR_TOKEN_HERE",
        "ENABLE_MCP_APPS": "true",
        // optional
        "FIGMA_READ_ONLY": "true" 
      }
    }
  }
}

🎨 Sparrow Bridge Plugin (Recommended Connection)

The Figma Sparrow Bridge plugin is the recommended way to connect Figma to the MCP server. It communicates via WebSocket — no special Figma launch flags needed, and it persists across Figma restarts.

Setup

Open Figma Desktop (normal launch — no debug flags needed)
Go to Plugins → Development → Import plugin from manifest...
Select figma-sparrow-bridge/manifest.json from the figma-sparrow-mcp directory
Run the plugin in your Figma file — it auto-connects via WebSocket (scans ports 9223–9232)
Ask your AI: "Check Figma status" to verify the connection

One-time import. Once imported, the plugin stays in your Development plugins list. Just run it whenever you want to use the MCP.

🎯 Test Your Connection

After setup, try these prompts:

Basic test (local mode):

Navigate to https://www.figma.com and check status

Design system test (requires auth):

Get design variables from [your Figma file URL]

Plugin test (Local Mode only):

Show me the primary font for [your theme name]

🔐 Authentication

Local Mode - Personal Access Token (Manual)

Visit https://help.figma.com/hc/en-us/articles/8085703771159-Manage-personal-access-tokens
Generate token
Add to MCP config as FIGMA_ACCESS_TOKEN environment variable

🛠️ Available Tools

Navigation & Status

figma_navigate - Open Figma URLs
figma_get_status - Check connection status

Console Debugging

figma_get_console_logs - Retrieve console logs
figma_watch_console - Real-time log streaming
figma_clear_console - Clear log buffer
figma_reload_plugin - Reload current page

Visual Debugging

figma_take_screenshot - Capture UI screenshots

Design System Extraction

figma_get_variables - Extract design tokens/variables
figma_get_component - Get component data (metadata or reconstruction spec)
figma_get_component_for_development - Component + image
figma_get_component_image - Just the image
figma_get_styles - Color, text, effect styles
figma_get_file_data - Full file structure
figma_get_file_for_plugin - Optimized file data

✏️ Design Creation (Local Mode + Sparrow Bridge)

figma_execute - Power tool: Run any Figma Plugin API code to create designs
- Create frames, shapes, text, components
- Apply auto-layout, styles, effects
- Build complete UI mockups programmatically
figma_arrange_component_set - Organize variants into professional component sets
- Convert multiple component variants into a proper Figma component set
- Applies native purple dashed border visualization automatically
- Creates white container frame with title, row labels, and column headers
- Row labels vertically centered with each grid row
- Column headers horizontally centered with each column
- Use natural language like "arrange these variants" or "organize as component set"
figma_set_description - Document components with rich descriptions
- Add descriptions to components, component sets, and styles
- Supports markdown formatting for rich documentation
- Descriptions appear in Dev Mode for developers

🔍 Design-Code Parity (All Modes)

figma_check_design_parity - Compare Figma component specs against code implementation, producing a scored diff report with actionable fix items
figma_generate_component_doc - Generate platform-agnostic markdown documentation by merging Figma design data with code-side info

🔧 Variable Management (Local Mode + Sparrow Bridge)

figma_create_variable_collection - Create new variable collections with modes
figma_create_variable - Create COLOR, FLOAT, STRING, or BOOLEAN variables
figma_update_variable - Update variable values in specific modes
figma_rename_variable - Rename variables while preserving values
figma_delete_variable - Delete variables
figma_delete_variable_collection - Delete collections and all their variables
figma_add_mode - Add modes to collections (e.g., "Dark", "Mobile")
figma_rename_mode - Rename existing modes
figma_batch_create_variables - Create up to 100 variables in one call (10-50x faster)
figma_batch_update_variables - Update up to 100 variable values in one call
figma_setup_design_tokens - Create complete token system (collection + modes + variables) atomically

📖 Detailed Tool Documentation

📖 Example Prompts

Plugin Debugging

Navigate to my Figma plugin and show me any console errors
Watch the console for 30 seconds while I test my plugin
Get the last 20 console logs

Design System Extraction

Get all design variables from https://figma.com/design/abc123
Extract color styles and show me the CSS exports
Get the Button component with a visual reference image
Get the Badge component in reconstruction format for programmatic creation

Design Creation (Local Mode)

Create a success notification card with a checkmark icon and message
Design a button component with hover and disabled states
Build a navigation bar with logo, menu items, and user avatar
Create a modal dialog with header, content area, and action buttons
Arrange these button variants into a component set
Organize my icon variants as a proper component set with the purple border

Variable Management (Local Mode)

Create a new color collection called "Brand Colors" with Light and Dark modes
Add a primary color variable with value #3B82F6 for Light and #60A5FA for Dark
Rename the "Default" mode to "Light Theme"
Add a "High Contrast" mode to the existing collection

Design-Code Parity

Compare the Button component in Figma against our React implementation
Check design parity for the Card component before sign-off
Generate component documentation for the Dialog from our design system

Visual Debugging

Take a screenshot of the current Figma canvas
Navigate to this file and capture what's on screen

🎨 AI-Assisted Design Creation

⚠️ Local Mode Only: This feature requires the Sparrow Bridge plugin and only works with Local Git installation.

One of the most powerful capabilities of this MCP server is the ability to design complete UI components and pages directly in Figma through natural language conversation with any MCP-compatible AI assistant like Claude Desktop or Claude Code.

What's Possible

Create original designs from scratch:

Design a login card with email and password fields, a "Forgot password?" link,
and a primary Sign In button. Use 32px padding, 16px border radius, and subtle shadow.

Leverage existing component libraries:

Build a dashboard header using the Avatar component for the user profile,
Button components for actions, and Badge components for notifications.

Generate complete page layouts:

Create a settings page with a sidebar navigation, a main content area with form fields,
and a sticky footer with Save and Cancel buttons.

How It Works

You describe what you want in plain English
The AI searches your component library using figma_search_components to find relevant building blocks
Components are instantiated with proper variants and properties via figma_instantiate_component
Custom elements are created using the full Figma Plugin API via figma_execute
Visual validation automatically captures screenshots and iterates until the design looks right

Who Benefits

Role	Use Case
Designers	Rapidly prototype ideas without manual frame-by-frame construction. Explore variations quickly by describing changes.
Developers	Generate UI mockups during planning discussions. Create visual specs without switching to design tools.
Product Managers	Sketch out feature concepts during ideation. Communicate visual requirements directly to stakeholders.
Design System Teams	Test component flexibility by generating compositions. Identify gaps in component coverage.
Agencies	Speed up initial concept delivery. Iterate on client feedback in real-time during calls.

Example Workflows

Brand New Design:

"Create a notification toast with an icon on the left, title and description text, and a dismiss button. Use our brand colors."

The AI creates custom frames, applies your design tokens, and builds the component from scratch.

Component Composition:

"Build a user profile card using the Avatar component (large size), two Button components (Edit Profile and Settings), and a Badge for the user's status."

The AI searches your library, finds the exact components, and assembles them with proper spacing and alignment.

Design Iteration:

"The spacing feels too tight. Increase the gap between sections to 24px and make the heading larger."

The AI modifies the existing design, takes a screenshot to verify, and continues iterating until you're satisfied.

Visual Validation

The AI automatically follows a validation workflow after creating designs:

Create → Execute the design code
Screenshot → Capture the result
Analyze → Check alignment, spacing, and visual balance
Iterate → Fix any issues detected
Verify → Final screenshot to confirm

This ensures designs aren't just technically correct—they look right.

How the Transport Works

The MCP server communicates via WebSocket through the Sparrow Bridge plugin
The server tries port 9223 first, then automatically falls back through ports 9224–9232 if needed
The plugin scans all ports in the range and connects to every active server it finds
All 56+ tools work through the WebSocket transport

Multiple files: The WebSocket server supports multiple simultaneous plugin connections — one per open Figma file. Each connection is tracked by file key with independent state (selection, document changes, console logs).

Environment variables:

FIGMA_WS_PORT — Override the preferred WebSocket port (default: 9223). The server will fall back through a 10-port range starting from this value if the preferred port is occupied.
FIGMA_WS_HOST — Override the WebSocket server bind address (default: localhost). Set to 0.0.0.0 when running inside Docker so the host machine can reach the MCP server.

Plugin Limitation: Only works in Local Git mode.

🧩 MCP Apps (Experimental)

Figma Sparrow MCP includes support for MCP Apps — rich interactive UI experiences that render directly inside any MCP client that supports the MCP Apps protocol extension. Built with the official @modelcontextprotocol/ext-apps SDK.

What are MCP Apps? Traditional MCP tools return text or images to the AI. MCP Apps go further — they render interactive HTML interfaces inline in the chat, allowing users to browse, filter, and interact with data directly without consuming AI context.

Token Browser

An interactive design token explorer.

Usage: Ask Claude to "browse the design tokens" or "show me the design tokens" while connected to a Figma file.

Features:

Browse all tokens organized by collection with expandable sections
Filter by type (Colors, Numbers, Strings) and search by name/description
Per-collection mode columns (Light, Dark, Custom) matching Figma's Variables panel
Color swatches, alias resolution, and click-to-copy on any value
Works without Enterprise plan via Sparrow Bridge (local mode)

Design System Dashboard

A Lighthouse-style health scorecard that audits your design system across six categories.

Usage: Ask Claude to "audit the design system" or "show me design system health" while connected to a Figma file.

Features:

Overall weighted score (0–100) with six category gauges: Naming, Tokens, Components, Accessibility, Consistency, Coverage
Expandable category sections with individual findings, severity indicators, and actionable details
Diagnostic locations linking findings to specific variables, components, or collections
Tooltips explaining each check's purpose and scoring criteria
Refresh button to re-run the audit without consuming AI context
Pure scoring engine with no external dependencies — all analysis runs locally

Enabling MCP Apps:

MCP Apps are enabled by default in the setup configurations above (via "ENABLE_MCP_APPS": "true"). If you set up before v1.10.0 and don't have this in your config, add it to your env section:

"env": {
  "FIGMA_ACCESS_TOKEN": "figd_YOUR_TOKEN_HERE",
  "ENABLE_MCP_APPS": "true"
}

Note: MCP Apps require an MCP client with ext-apps protocol support (e.g. Claude Desktop). This feature is experimental and the protocol may evolve.

🚀 Advanced Topics

Architecture - How it works under the hood
Troubleshooting - Common issues and solutions

💻 Development

git clone https://github.com/TrueSparrowSystems/figma-sparrow-mcp.git
cd figma-sparrow-mcp
npm install

# Local mode development
npm run dev:local

# Cloud mode development
npm run dev

# Build
npm run build

📖 Development Guide

Name		Name	Last commit message	Last commit date
Latest commit History 269 Commits
.claude		.claude
docs		docs
figma-sparrow-bridge		figma-sparrow-bridge
scripts		scripts
src		src
tests		tests
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.prettierrc		.prettierrc
README.md		README.md
biome.json		biome.json
jest.config.cjs		jest.config.cjs
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsconfig.local.json		tsconfig.local.json
vite.config.ts		vite.config.ts

Folders and files

Latest commit

History

Repository files navigation

Figma Sparrow MCP Server

What is this?

⚡ Quick Start

For Contributors: Local Git Mode

Quick Setup

Configure Your MCP Client

🎨 Sparrow Bridge Plugin (Recommended Connection)

Setup

🎯 Test Your Connection

🔐 Authentication

Local Mode - Personal Access Token (Manual)

🛠️ Available Tools

Navigation & Status

Console Debugging

Visual Debugging

Design System Extraction

✏️ Design Creation (Local Mode + Sparrow Bridge)

🔍 Design-Code Parity (All Modes)

🔧 Variable Management (Local Mode + Sparrow Bridge)

📖 Example Prompts

Plugin Debugging

Design System Extraction

Design Creation (Local Mode)

Variable Management (Local Mode)

Design-Code Parity

Visual Debugging

🎨 AI-Assisted Design Creation

What's Possible

How It Works

Who Benefits

Example Workflows

Visual Validation

How the Transport Works

🧩 MCP Apps (Experimental)

Token Browser

Design System Dashboard

🚀 Advanced Topics

💻 Development

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages