内容
# Figma CLI
> Figma MCP 命令行工具 — **给 AI Agent 用的 Figma 桥接器**
>
> 📖 关于 Figma MCP 认证，看这篇：[Kimi 用不了 Figma？看这里解决](https://juejin.cn/spost/7647784370972360755)
将 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）
---
## 安装
```bash
pnpm link # 本地 link（开发用）
# 或
pnpm install -g @boltdoggy/figma # 全局安装（发布后）
```
> 也可以直接用 `npx -y @boltdoggy/figma` 无需安装即可运行（适合临时使用或 MCP 配置）。
## 快速开始
### 1. 认证
```bash
# 查看认证状态
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` |
```json
{
"mcpServers": {
"figma": {
"command": "figma",
"args": ["mcp"]
}
}
}
```
**方式 B — 无需安装，用 `npx -y` 自动拉取**（推荐）：
```json
{
"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
```bash
# 解析 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。
```bash
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` 传入。
```bash
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 调用场景。
```bash
figma auth set figd_xxxxxxxxxxxx
```
也可以通过环境变量设置（优先级更高）：
```bash
export FIGMA_ACCESS_TOKEN=figd_xxxxxxxxxxxx
```
### OAuth 2.0 with PKCE（MCP 模式）
MCP 完整读写能力需要 OAuth 认证：
```bash
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？看这里解决](https://juejin.cn/spost/7647784370972360755)
---
## 开发
```bash
# 安装依赖
pnpm install
# 类型检查
pnpm typecheck
# 编译
pnpm build
# 开发模式（直接运行 ts）
pnpm dev -- <args>
# 发布版
pnpm build && figma <command>
```
