figma-pilot

A bridge that enables AI agents to create and modify Figma designs through natural language.

让 AI 代理（如 Claude Code、Gemini CLI）能够直接操作 Figma 设计文件。

One-Line Install (Local) / 一键安装

git clone https://github.com/youware-labs/figma-pilot.git && cd figma-pilot && ./scripts/install.sh

This will:

• Build the project
• Configure Claude Code MCP
• Open Figma plugin folder for manual import

Quick Start (For Users) / 快速开始

1. Configure MCP / 配置 MCP

Claude Code:

claude mcp add figma-pilot -- npx @youware-labs/figma-pilot-mcp

Claude Desktop / Cursor / Gemini CLI:

Add to your MCP config file:

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

2. Install Figma Plugin / 安装 Figma 插件

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

3. Start Using / 开始使用

Ask your AI agent:

"Create a card component with a header and body"
"Change the selected frame's background to blue"
"Create a navigation bar with logo and menu items"
"Check accessibility and fix any issues"

How It Works / 工作原理

┌─────────────┐     stdio      ┌─────────────────┐     HTTP      ┌──────────────┐
│   Claude    │ ◄────────────► │  MCP Server     │ ◄───────────► │ Figma Plugin │
│   (or AI)   │                │  (with bridge)  │   port 38451  │              │
└─────────────┘                └─────────────────┘               └──────────────┘

The MCP server includes a built-in HTTP bridge. No separate server process needed.

Available MCP Tools / 可用工具

Tool	Description
figma_status	Check connection status
figma_selection	Get current selection
figma_query	Query element by ID or name
figma_create	Create elements (frame, text, rectangle, etc.)
figma_modify	Modify element properties
figma_delete	Delete elements
figma_append	Move elements into a container
figma_list_components	List available components
figma_instantiate	Create component instance
figma_to_component	Convert selection to component
figma_create_variants	Create component variants
figma_ensure_accessibility	Check and fix accessibility
figma_export	Export as image

Development / 开发

For contributors and local development:

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

# Run MCP server locally
bun run packages/mcp-server/dist/index.js

# Or use CLI directly
bun run cli status
bun run cli create --type frame --name "Test" --width 200 --height 100

Project Structure / 项目结构

figma-pilot/
├── packages/
│   ├── cli/           # CLI application
│   ├── plugin/        # Figma plugin
│   ├── mcp-server/    # MCP server (npm package)
│   └── shared/        # Shared TypeScript types
├── scripts/
│   └── package-plugin.sh  # Script to package plugin for releases
├── SKILL.md           # Detailed documentation for AI agents
└── README.md

Creating a Release / 发布版本

# Build everything
bun run build

# Package plugin for GitHub release
chmod +x scripts/package-plugin.sh
./scripts/package-plugin.sh 0.1.0

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

# Create GitHub release with plugin zip
gh release create v0.1.0 dist/releases/figma-pilot-plugin-v0.1.0.zip \
  --title "v0.1.0" \
  --notes "Initial release"

Troubleshooting / 故障排除

Plugin not connecting / 插件无法连接

1. Make sure the MCP server is running (check Claude Code or your AI client)
2. The plugin should show "Connected" status
3. Try closing and reopening the plugin in Figma

Port 38451 already in use / 端口被占用

lsof -i :38451
kill <PID>

For AI Agent Developers / AI 开发者

The SKILL.md file contains comprehensive documentation designed for AI agents, including:

• Complete command reference with JSON schemas
• Common patterns and workflows
• Best practices for creating complex layouts

License

MIT