微信扫一扫README
🚀 figma-pilot
AI 智能体通过代码执行控制 Figma
🚀 快速开始
前提条件
- Node.js >= 18
- Figma 桌面应用程序
- 兼容 MCP 的 AI 客户端（Claude Desktop、Claude Code、Cursor、Codex 等）
1. 安装 MCP 服务器
# Claude Code
claude mcp add figma-pilot -- npx @youware-labs/figma-pilot-mcp
# 其他 MCP 客户端 - 添加到你的 MCP 配置中：
{
"mcpServers": {
"figma-pilot": {
"command": "npx",
"args": ["@youware-labs/figma-pilot-mcp"]
}
}
}
配置文件位置：
- Claude Desktop：
~/.config/claude/claude_desktop_config.json（macOS/Linux） - Cursor：
~/.cursor/mcp.json
2. 安装技能（推荐）
skills/ 文件夹包含帮助 AI 智能体正确使用 figma_execute 的 API 文档。将其安装到你的 AI 客户端的技能目录中：
| AI 客户端 | 技能目录 |
|-----------|-----------------|
| Claude Code / Codex | ~/.codex/skills/figma-pilot |
| Cursor | ~/.cursor/skills-cursor/figma-pilot |
| Claude Desktop | ~/.claude/skills/figma-pilot |
安装完成后，重启你的 AI 客户端以加载新技能。
3. 安装 Figma 插件
- 从 Releases 下载
figma-pilot-plugin-vX.X.X.zip - 解压文件
- 在 Figma 中：插件 > 开发 > 从清单导入插件...
- 从解压后的文件夹中选择
manifest.json - 运行：插件 > 开发 > figma-pilot
4. 验证连接
向你的 AI 智能体询问：
检查 Figma 连接状态
✨ 主要特性
本项目受到 Anthropic 的 Code execution with MCP 方法的启发。
与暴露数十个单独的 MCP 工具（这会使上下文窗口臃肿并减慢智能体速度）不同，figma-pilot 仅提供 3 个工具：
| 工具 | 描述 |
|------|-------------|
| figma_status | 检查连接状态 |
| figma_execute | 使用完整的 Figma API 执行 JavaScript 代码 |
| figma_get_api_docs | 获取 API 文档 |
AI 编写代码与 Figma 进行交互。这意味着：
- 工具定义中的 令牌减少 90% 以上
- 批量操作 - 一次调用中修改 100 个元素
- 数据过滤 - 在返回上下文之前过滤结果
- 复杂工作流 - 循环、条件语句、错误处理
💻 使用示例
基础用法
自然语言
创建一个带有标题和描述的卡片
AI 生成的代码
创建卡片：
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' }
]
});
批量修改元素：
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`);
可访问性检查：
const result = await figma.accessibility({
target: 'page',
level: 'AA',
autoFix: true
});
console.log(`Fixed ${result.fixedCount} of ${result.totalIssues} issues`);
📚 详细文档
// 查询与修改
figma.query({ target }) // 查询元素
figma.create({ type, ... }) // 创建元素
figma.modify({ target, ... }) // 修改元素
figma.delete({ target }) // 删除元素
figma.append({ target, parent }) // 移动到容器中
// 组件
figma.listComponents() // 列出组件
figma.instantiate({ component }) // 创建实例
figma.toComponent({ target }) // 转换为组件
figma.createVariants({ ... }) // 创建变体
// 可访问性与令牌
figma.accessibility({ target }) // WCAG 检查
figma.createToken({ ... }) // 创建设计令牌
figma.bindToken({ ... }) // 将令牌绑定到元素
// 导出
figma.export({ target, format }) // 导出为图像
完整文档：skills/SKILL.md
🔧 技术细节
┌─────────────┐ stdio ┌─────────────────┐ HTTP ┌──────────────┐
│ MCP Client │ <------------> │ MCP Server │ <-----------> │ Figma Plugin │
│ │ │ (with bridge) │ port 38451 │ │
└─────────────┘ └─────────────────┘ └──────────────┘
🛠️ 开发
项目结构
figma-pilot/
├── packages/
│ ├── cli/ # CLI 应用程序
│ ├── plugin/ # Figma 插件
│ ├── mcp-server/ # MCP 服务器（npm 包）
│ └── shared/ # 共享的 TypeScript 类型
├── scripts/
│ ├── install.sh # 安装脚本
│ └── package-plugin.sh
└── skills/ # AI 智能体的 API 文档
从源代码构建
git clone https://github.com/youware-labs/figma-pilot.git
cd figma-pilot
bun install && bun run build
创建版本
# 构建并打包
bun run build
./scripts/package-plugin.sh 0.x.x
# 发布到 npm
cd packages/mcp-server && npm publish --access public
# 创建 GitHub 版本
gh release create v0.x.x dist/releases/figma-pilot-plugin-v0.x.x.zip \
--title "v0.x.x" \
--notes "Release notes here"
🐞 故障排除
插件无法连接
- 确保 MCP 服务器正在运行（检查你的 AI 客户端的 MCP 状态）
- 插件应在 Figma 中显示“已连接”
- 尝试重新打开插件
- 检查端口 38451 是否被阻塞
端口 38451 已被使用
lsof -i :38451
kill <PID>
找不到 MCP 服务器
对于离线使用，全局安装：
npm install -g @youware-labs/figma-pilot-mcp
插件错误：“ENOENT: no such file or directory, lstat '.../dist/main.js'”
此错误表示插件目录中缺少 dist 文件夹。这可能发生在以下情况：
- 下载的 zip 文件不完整
- 你直接使用源代码而未进行构建
解决方案： 如果你有源代码，请构建插件：
cd packages/plugin
bun install
bun run build
或者从项目根目录构建：
bun run build:plugin
构建完成后，验证 packages/plugin/dist/main.js 和 packages/plugin/dist/ui.html 是否存在，然后在 Figma 中重新导入插件。
📄 许可证
MIT - YouWare Labs