Figma MCP 命令行工具 — 给 AI Agent 用的 Figma 桥接器
📖 关于 Figma MCP 认证,看这篇:Kimi 用不了 Figma?看这里解决
将 Figma 的完整设计读写能力带到命令行,专为 Claude Code / Cursor 等 AI Agent 设计。
本工具不封装 Figma REST API,而是作为 Figma Remote MCP Server 的代理和前端:
figma mcp— 启动 stdio MCP 代理,供 AI Agent 直接连接并使用所有 Figma MCP 工具figma use-figma/figma call— 从终端直接调用 MCP 工具,无需 Agent 中间层figma auth— 一站式认证管理(PAT + OAuth)
pnpm link # 本地 link(开发用) # 或 pnpm install -g @boltdoggy/figma # 全局安装(发布后)
也可以直接用
npx -y @boltdoggy/figma无需安装即可运行(适合临时使用或 MCP 配置)。
# 查看认证状态 figma auth status # 方式 A: OAuth 登录(推荐,支持 MCP 完整能力) figma auth oauth-login # 自动打开浏览器完成 PKCE 授权 # 方式 B: 设置 Personal Access Token(只读操作需要) figma auth set figd_xxxxxxxxxxxx figma auth test # 测试 PAT 有效性
在 Claude Code、Cursor 或 Windsurf 中,将 figma mcp 注册为 stdio MCP Server。
方式 A — 全局安装后直接引用(本地已 pnpm link 或 npm i -g):
| 平台 | 配置位置 |
|---|---|
| Claude Code | .claude/settings.local.json 或 ~/.claude/settings.json |
| Cursor | .cursor/mcp.json |
| Windsurf | .windsurf/mcp.json |
{
"mcpServers": {
"figma": {
"command": "figma",
"args": ["mcp"]
}
}
}方式 B — 无需安装,用 npx -y 自动拉取(推荐):
{
"mcpServers": {
"figma": {
"command": "npx",
"args": ["-y", "@boltdoggy/figma", "mcp"]
}
}
}
npx -y方式无需预先全局安装,每次自动从 npm 下载并运行最新版本。适合首次配置、跨机器使用或 CI 环境。
配置后 Agent 自动获得 use_figma、get_design_context、get_screenshot、search_design_system 等全部 Figma MCP 工具,可直接读取或写入 Figma 设计文件。
# 解析 Figma URL figma url "https://figma.com/design/abc123/MyDesign?node-id=1-2" # 在 Figma 文件中创建设计(内联代码) figma use-figma abc123 --code ' const frame = figma.createFrame() frame.resize(375, 812) frame.fills = [{type: "SOLID", color: {r: 1, g: 1, b: 1}}] frame.name = "iPhone Frame" figma.currentPage.appendChild(frame) ' # 从文件读取设计代码 figma use-figma abc123 -f ./my-design-code.js # 调用任意 MCP 工具 figma call get_screenshot --arg.fileKey=abc123 --arg.nodeId=1-2 figma call get_design_context --arg.fileKey=abc123 --arg.nodeId=1-2 figma call search_design_system --arg.fileKey=abc123 --arg.query=button
| 子命令 | 功能 |
|---|---|
figma auth set <token> |
设置 Personal Access Token |
figma auth status |
查看 PAT 和 OAuth 的详细状态 |
figma auth clear |
清除 PAT |
figma auth test |
测试 PAT 有效性(调用 /v1/me) |
figma auth oauth-login |
OAuth 登录 — 打开浏览器完成 PKCE 授权流程 |
figma auth oauth-logout |
清除 OAuth 令牌 |
启动 stdio MCP 代理,将所有 Figma Remote MCP Server 的工具透传给 AI Agent。
figma mcp
这是核心能力:Agent 通过 stdio 连接后,可以获得 use_figma、get_design_context、get_screenshot、search_design_system 等全部 Figma MCP 工具。
在指定 Figma 文件中运行 JavaScript(Figma Plugin API),完成创建/编辑/同步等设计操作。
| 选项 | 说明 |
|---|---|
-c, --code <code> |
内联 JS 代码 |
-f, --file <path> |
从文件读取 JS 代码 |
-d, --description <desc> |
操作描述(默认 figma-cli call) |
通用方式调用 Figma MCP 工具,参数用 --arg.key=value 传入。
figma call get_screenshot --arg.fileKey=abc123 --arg.nodeId=1-2 figma call get_libraries --arg.fileKey=abc123
从 Figma URL 提取 fileKey、nodeId 和 branchKey。
适用于 CI/CD 或传统 REST API 调用场景。
figma auth set figd_xxxxxxxxxxxx也可以通过环境变量设置(优先级更高):
export FIGMA_ACCESS_TOKEN=figd_xxxxxxxxxxxxMCP 完整读写能力需要 OAuth 认证:
figma auth oauth-login
流程:
- 自动发现 Figma OAuth 端点
- 动态注册 OAuth 客户端
- 启动本地回调服务器 → 打开浏览器授权
- 使用 PKCE 交换 access + refresh token
- 令牌持久化存储,后续自动复用
注意: Figma Remote MCP Server 目前为 beta 阶段。Starter 免费版账户每月限制 6 次 MCP 工具调用。OAuth 客户端凭证需在 Figma OAuth 白名单中。
- TypeScript — 类型安全
- Commander.js — CLI 框架
- @modelcontextprotocol/sdk — MCP 协议(Stdio Server + Streamable HTTP Client)
- Chalk + Ora — 颜色输出和加载动画
- Conf — 配置文件持久化
- Figma Remote MCP Server — 完整设计读写能力
关于 Figma MCP 认证问题的详细解读:Kimi 用不了 Figma?看这里解决
# 安装依赖 pnpm install # 类型检查 pnpm typecheck # 编译 pnpm build # 开发模式(直接运行 ts) pnpm dev -- <args> # 发布版 pnpm build && figma <command>