figma-pilot

AI agents control Figma through code execution.

English | 中文

Demo

OpenAI Landing Page

Prompt: "Create an OpenAI style landing page introducing the upcoming GPT 5.3 release on Figma"

Manus Design System

Prompt: "Generate a Manus design system components based on the screenshot, on Figma"

Design Philosophy

This project is inspired by Anthropic's Code execution with MCP approach.

Instead of exposing dozens of individual MCP tools (which bloat the context window and slow down agents), figma-pilot provides only 3 tools:

Tool	Description
figma_status	Check connection status
figma_execute	Execute JavaScript code with full Figma API
figma_get_api_docs	Get API documentation

The AI writes code to interact with Figma. This means:

• 90%+ fewer tokens in tool definitions
• Batch operations - modify 100 elements in one call
• Data filtering - filter results before returning to context
• Complex workflows - loops, conditionals, error handling

Quick Start

Prerequisites

• Node.js >= 18
• Figma Desktop app
• An MCP-compatible AI client (Claude Desktop, Claude Code, Cursor, Codex, etc.)

1. Install MCP Server

# Claude Code
claude mcp add figma-pilot -- npx @youware-labs/figma-pilot-mcp

# Other MCP clients - add to your MCP config:

{
  "mcpServers": {
    "figma-pilot": {
      "command": "npx",
      "args": ["@youware-labs/figma-pilot-mcp"]
    }
  }
}

Config locations:

• Claude Desktop: ~/.config/claude/claude_desktop_config.json (macOS/Linux)
• Cursor: ~/.cursor/mcp.json

2. Install Skill (Recommended)

The skills/ folder contains API documentation that helps AI agents use figma_execute correctly. Install it to your AI client's skill directory:

AI Client	Skill Directory
Claude Code / Codex	~/.codex/skills/figma-pilot
Cursor	~/.cursor/skills-cursor/figma-pilot
Claude Desktop	~/.claude/skills/figma-pilot

After installation, restart your AI client to pick up the new skill.

3. Install Figma Plugin

1. Download figma-pilot-plugin-vX.X.X.zip from Releases
2. Unzip the file
3. In Figma: Plugins > Development > Import plugin from manifest...
4. Select manifest.json from the unzipped folder
5. Run: Plugins > Development > figma-pilot

4. Verify Connection

Ask your AI agent:

Check the Figma connection status

Usage Examples

Natural Language

Create a card with a title and description

What the AI Generates

Creating a Card:

await figma.create({
  type: 'card',
  name: 'User Card',
  children: [
    { type: 'text', content: 'Card Title', fontSize: 18, fontWeight: 600 },
    { type: 'text', content: 'Description here', fontSize: 14, fill: '#666' }
  ]
});

Batch Modifying Elements:

const { nodes } = await figma.query({ target: 'selection' });
const rects = nodes.filter(n => n.type === 'RECTANGLE');
for (const rect of rects) {
  await figma.modify({ target: rect.id, fill: '#0066FF', cornerRadius: 8 });
}
console.log(`Modified ${rects.length} rectangles`);

Accessibility Check:

const result = await figma.accessibility({ 
  target: 'page', 
  level: 'AA', 
  autoFix: true 
});
console.log(`Fixed ${result.fixedCount} of ${result.totalIssues} issues`);

API Reference

// Query & Modify
figma.query({ target })           // Query elements
figma.create({ type, ... })       // Create elements  
figma.modify({ target, ... })     // Modify elements
figma.delete({ target })          // Delete elements
figma.append({ target, parent })  // Move into container

// Components
figma.listComponents()            // List components
figma.instantiate({ component })  // Create instance
figma.toComponent({ target })     // Convert to component
figma.createVariants({ ... })     // Create variants

// Accessibility & Tokens
figma.accessibility({ target })   // WCAG checking
figma.createToken({ ... })        // Create design token
figma.bindToken({ ... })          // Bind token to element

// Export
figma.export({ target, format })  // Export as image

Full documentation: skills/SKILL.md

Architecture

┌─────────────┐     stdio      ┌─────────────────┐     HTTP      ┌──────────────┐
│ MCP Client  │ <------------> │  MCP Server     │ <-----------> │ Figma Plugin │
│             │                │  (with bridge)  │   port 38451  │              │
└─────────────┘                └─────────────────┘               └──────────────┘

Development

Project Structure

figma-pilot/
├── packages/
│   ├── cli/           # CLI application
│   ├── plugin/        # Figma plugin
│   ├── mcp-server/    # MCP server (npm package)
│   └── shared/        # Shared TypeScript types
├── scripts/
│   ├── install.sh     # Installation script
│   └── package-plugin.sh
└── skills/            # API documentation for AI agents

Building from Source

git clone https://github.com/youware-labs/figma-pilot.git
cd figma-pilot
bun install && bun run build

Creating a Release

# Build and package
bun run build
./scripts/package-plugin.sh 0.x.x

# Publish to npm
cd packages/mcp-server && npm publish --access public

# Create GitHub release
gh release create v0.x.x dist/releases/figma-pilot-plugin-v0.x.x.zip \
  --title "v0.x.x" \
  --notes "Release notes here"

Troubleshooting

Plugin Not Connecting

1. Ensure MCP server is running (check your AI client's MCP status)
2. Plugin should show "Connected" in Figma
3. Try reopening the plugin
4. Check that port 38451 is not blocked

Port 38451 Already in Use

lsof -i :38451
kill <PID>

MCP Server Not Found

For offline use, install globally:

npm install -g @youware-labs/figma-pilot-mcp

Plugin Error: "ENOENT: no such file or directory, lstat '.../dist/main.js'"

This error means the dist folder is missing from the plugin directory. This can happen if:

1. The downloaded zip file was incomplete
2. You're using the source code directly without building

Solution:

If you have the source code, build the plugin:

cd packages/plugin
bun install
bun run build

Or build from the project root:

bun run build:plugin

After building, verify that packages/plugin/dist/main.js and packages/plugin/dist/ui.html exist, then import the plugin again in Figma.

License

MIT - YouWare Labs