上手指南#

通过本地 MCP 桥，将 Figma Desktop 连接到 AI Agent。

支持的 MCP 客户端（详细步骤）：接入 AI Agent — Cursor、Claude Code、Codex、Qoder、CodeBuddy、Trae。

#环境要求

• Figma Desktop（推荐；浏览器标签可能休眠导致 WebSocket 断开）
• Node.js ≥ 20
• pnpm ≥ 9（从源码构建时需要）
• 支持 MCP 的 Agent（Cursor / Claude Code / Codex / Qoder / CodeBuddy / Trae）

#路径 A — 使用已发布包（最快）

#1. 安装插件

1. 打开 GitHub Releases
2. 下载 figma-agent-plugin-vX.Y.Z.zip（与即将使用的 MCP 版本一致）
3. 解压
4. Figma Desktop → Plugins → Development → Import plugin from manifest…
5. 选择解压目录中的 manifest.json
6. 运行 Plugins → Development → Figma Agent Kit

MCP 启动后，确认桥状态为绿色（或可手动重连）：

点击标题栏 最小化 可进入仅显示选区的紧凑窗口：

齿轮菜单（语言、模型、提示词、检查更新）：

#2. 配置 MCP

各客户端完整说明见：接入 AI Agent（Cursor、Claude Code、Codex、Qoder、CodeBuddy、Trae）。

Cursor 快速示例 — ~/.cursor/mcp.json 或项目 .cursor/mcp.json：

{
  "mcpServers": {
    "figma-agent-mcp": {
      "command": "npx",
      "args": ["-y", "figma-agent-mcp"]
    }
  }
}

自定义端口（必须与插件构建一致）：

"env": { "FIGMA_AGENT_MCP_PORT": "1998" }

修改后重启 Agent / MCP。在 Cursor 的 MCP 面板应看到 37 tools enabled：

#3. 冒烟测试

让 Agent 依次调用：

1. list_files — 应列出当前打开文件
2. get_selection — 先在画布选中 Frame
3. get_node / get_screenshot — 验证读路径
4. 可选：save_screenshots，scale: 3，compress: true

#路径 B — 从源码开发

git clone https://github.com/ChinaCarlos/figma-agent-kit.git
cd figma-agent-kit
pnpm install
pnpm build:all

导入插件：

packages/figma-agent-plugin/manifest.json

手动启动 MCP（可选）：

pnpm start:mcp

或让 Cursor 指向构建产物：

{
  "mcpServers": {
    "figma-agent-mcp": {
      "command": "node",
      "args": ["/ABS/PATH/figma-agent-kit/packages/figma-agent-mcp/dist/index.js"]
    }
  }
}

监听模式：

pnpm dev          # 插件
pnpm dev:mcp      # MCP TypeScript watch

改 UI/桥后：在 Figma 中 Reload 插件，并重启 MCP 客户端。

#端口同步

默认桥端口 1998，来自 bridge.config.json。

pnpm sync:bridge   # predev / prebuild 也会执行

改端口后：sync → 重建插件 → 重新 Import/Reload → 用相同 FIGMA_AGENT_MCP_PORT 重启 MCP。

#可选：插件内 AI

重命名与视觉分组需要在插件设置中配置 OpenAI 兼容 API Key。见 AI 功能。
MCP 桥工具不需要该 Key。

#切图（插件 UI）

见 导出切图。

#下一步