Figma CLI

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 配置）。

快速开始

1. 认证

# 查看认证状态
figma auth status

# 方式 A: OAuth 登录（推荐，支持 MCP 完整能力）
figma auth oauth-login    # 自动打开浏览器完成 PKCE 授权

# 方式 B: 设置 Personal Access Token（只读操作需要）
figma auth set figd_xxxxxxxxxxxx
figma auth test            # 测试 PAT 有效性

2. 配置 MCP Server（供 AI Agent 使用）

在 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 设计文件。

3. 直接从终端操作 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 — 认证管理

| 子命令 | 功能 | |--------|------| | 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 令牌 |

figma mcp — MCP 代理

启动 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 use-figma <fileKey> — 执行设计操作

在指定 Figma 文件中运行 JavaScript（Figma Plugin API），完成创建/编辑/同步等设计操作。

| 选项 | 说明 | |------|------| | -c, --code <code> | 内联 JS 代码 | | -f, --file <path> | 从文件读取 JS 代码 | | -d, --description <desc> | 操作描述（默认 figma-cli call） |

figma call <toolName> — 调用任意 MCP 工具

通用方式调用 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 <figmaUrl> — URL 解析

从 Figma URL 提取 fileKey、nodeId 和 branchKey。

认证

Personal Access Token（PAT）

适用于 CI/CD 或传统 REST API 调用场景。

figma auth set figd_xxxxxxxxxxxx

也可以通过环境变量设置（优先级更高）：

export FIGMA_ACCESS_TOKEN=figd_xxxxxxxxxxxx

OAuth 2.0 with PKCE（MCP 模式）

MCP 完整读写能力需要 OAuth 认证：

figma auth oauth-login

流程：

1. 自动发现 Figma OAuth 端点
2. 动态注册 OAuth 客户端
3. 启动本地回调服务器 → 打开浏览器授权
4. 使用 PKCE 交换 access + refresh token
5. 令牌持久化存储，后续自动复用

注意: 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>