内容
# Figma MCP 桥接
[](https://www.npmjs.com/package/mcp-figma-bridge)
[](https://www.npmjs.com/package/mcp-figma-bridge)
[](https://github.com/sonht113/mcp-figma-bridge/releases)
[](./LICENSE)
[](https://www.npmjs.com/package/mcp-figma-bridge)
连接任意 MCP 客户端（**Grok**、**Claude**、**Codex**、**OpenCode**、**Cursor**等）到 **Figma Desktop**，实现实时通信，无需 Figma REST API 密钥。
| | |
|--|--|
| **npm** | [`mcp-figma-bridge`](https://www.npmjs.com/package/mcp-figma-bridge) |
| **GitHub** | [`sonht113/mcp-figma-bridge`](https://github.com/sonht113/mcp-figma-bridge) |
| **发布版本** | [GitHub Releases](https://github.com/sonht113/mcp-figma-bridge/releases) （标签 `v*` ↔ npm 版本） |
| **变更日志** | [CHANGELOG.md](./CHANGELOG.md) |
| **CLI** | `mcp-figma-bridge` / `npx -y mcp-figma-bridge` |
```
MCP 客户端（Grok / Claude / Codex / OpenCode / …）
│ 标准输入输出 JSON-RPC
▼
npx mcp-figma-bridge → mcp-server/index.js
│ （自动启动桥接服务，如果需要）
│ HTTP POST /cmd
▼
mcp-server/bridge.js (:3765)
│ 长轮询 GET /poll
▼
figma-plugin/ui.html ↔ code.js ↔ Figma 插件 API
```
### 检查已安装/最新版本
```bash
npm view mcp-figma-bridge version # 最新版本在 npm 上
npm list -g mcp-figma-bridge # 全局安装（如果有）
npx -y mcp-figma-bridge help # 运行软件包；查看 npm 版本信息
```
GitHub 标签 **vX.Y.Z** 匹配 npm **X.Y.Z** （semver 版本，无前导 `v`）。
---
## 先决条件
- **Node.js ≥ 18** (`node --version`)
- **[Figma Desktop](https://www.figma.com/downloads/)** （网页版无法运行此本地插件）
- 支持 MCP 的客户端（参见 [配置 MCP 客户端](#configure-mcp-clients)）
---
## 快速开始（推荐）
### 1. 导入 Figma 插件（一次性操作）
```bash
npx -y mcp-figma-bridge plugin-path
```
复制打印的绝对路径，然后：
1. 打开 **Figma Desktop**
2. **插件 → 开发 → 从清单导入插件…**
3. 选择该 `manifest.json`
4. 打开设计文件 → **插件 → 开发 → MCP Bridge**
5. 端口 `3765` → **启动** （徽章 **已连接** = 成功）
> Figma 不会自动从 npm 加载插件。`plugin-path` 仅告诉您已安装软件包的位置。
### 2. 配置您的 MCP 客户端
使用 **`npx`**，您无需克隆路径：
| 字段 | 值 |
|-------|--------|
| 命令 | `npx` |
| 参数 | `-y`，`mcp-figma-bridge` |
| 环境变量（可选） | `BRIDGE_PORT=3765`，`BRIDGE_HOST=127.0.0.1` |
MCP 进程在端口 `3765` 上**自动启动** HTTP 桥接服务，如果它尚未运行。设置 `BRIDGE_AUTO_START=0` 以禁用此功能。
在保存配置后重启客户端。
### 3. 健康检查
```bash
curl -s http://127.0.0.1:3765/health
```
---
## CLI
```bash
npx -y mcp-figma-bridge # MCP 标准输入输出（默认；自动启动桥接服务）
npx -y mcp-figma-bridge mcp # 相同
npx -y mcp-figma-bridge bridge # 仅 HTTP 桥接服务
npx -y mcp-figma-bridge plugin-path # 插件清单文件的绝对路径
npx -y mcp-figma-bridge help
```
| 变量 | 默认值 | 含义 |
|----------|---------|---------|
| `BRIDGE_PORT` | `3765` | HTTP 端口 |
| `BRIDGE_HOST` | `127.0.0.1` | 绑定/连接地址 |
| `BRIDGE_AUTO_START` | `1` | 设置 `0` / `false` 以跳过自动启动 |
| `CMD_TIMEOUT_MS` | `35000` | MCP → 桥接服务命令超时 |
---
## 配置 MCP 客户端
所有示例的共享设置：
| 字段 | 值 |
|-------|--------|
| 命令 | `npx` |
| 参数 | `-y`，`mcp-figma-bridge` |
| 环境变量 | `BRIDGE_PORT=3765`，`BRIDGE_HOST=127.0.0.1` （可选） |
从 **git 克隆**，您仍然可以使用绝对路径：
```text
命令：node
参数： /ABSOLUTE/PATH/TO/figma-mcp-bridge/mcp-server/index.js
```
---
### Grok（xAI / Grok CLI · TUI）
**配置文件：** `~/.grok/config.toml`
**或项目：** `<repo>/.grok/config.toml`
```toml
[mcp_servers.figma-bridge]
command = "npx"
args = ["-y", "mcp-figma-bridge"]
env = { BRIDGE_PORT = "3765", BRIDGE_HOST = "127.0.0.1" }
enabled = true
startup_timeout_sec = 30
tool_timeout_sec = 60
# 可选：较大的工具结果（页面树）以防止客户端截断
[mcp]
max_output_bytes = 100000
```
**CLI 替代：**
```bash
grok mcp add figma-bridge \
-e BRIDGE_PORT=3765 \
-e BRIDGE_HOST=127.0.0.1 \
-- npx -y mcp-figma-bridge
```
**验证：**
```bash
grok mcp list
grok mcp doctor figma-bridge
```
在会话中： `/mcps` → 如果您在运行过程中编辑了配置，请刷新 `r`。
工具显示为 `figma-bridge__list_page_frames`、`figma-bridge__get_node_tree` 等。
---
### Claude Desktop
**配置文件：
| 操作系统 | 路径 |
|----|------|
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
| Linux | `~/.config/Claude/claude_desktop_config.json` |
```json
{
"mcpServers": {
"figma-bridge": {
"command": "npx",
"args": ["-y", "mcp-figma-bridge"],
"env": {
"BRIDGE_PORT": "3765",
"BRIDGE_HOST": "127.0.0.1"
}
}
}
}
```
另请参阅此仓库中的 `claude_desktop_config.example.json`。
在保存后重启 **Claude Desktop**。如果工具未显示，请检查 **设置 → 开发者** （或 MCP 日志）。
---
### Claude Code（CLI）
**项目**（推荐）：`.mcp.json` 在项目根目录。
```bash
claude mcp add figma-bridge -- npx -y mcp-figma-bridge
```
**`.mcp.json`（项目）：**
```json
{
"mcpServers": {
"figma-bridge": {
"command": "npx",
"args": ["-y", "mcp-figma-bridge"],
"env": {
"BRIDGE_PORT": "3765",
"BRIDGE_HOST": "127.0.0.1"
}
}
}
}
```
在更改 MCP 配置后重启 Claude Code 会话。
---
### OpenAI Codex（CLI / IDE）
**配置文件：** `~/.codex/config.toml`
**或项目：** `.codex/config.toml` （受信任的项目）
> 顶级键是 **`mcp_servers`** （下划线），而不是 `mcpServers`。
```toml
[mcp_servers.figma-bridge]
command = "npx"
args = ["-y", "mcp-figma-bridge"]
startup_timeout_sec = 30
[mcp_servers.figma-bridge.env]
BRIDGE_PORT = "3765"
BRIDGE_HOST = "127.0.0.1"
```
重启 Codex / 打开新线程。使用 `/mcp` （或等效命令）确认工具。
---
### OpenCode
**配置文件：** `~/.config/opencode/opencode.json` 或 `opencode.jsonc`
**或项目：** `opencode.json` 在仓库中
```json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"figma-bridge": {
"type": "local",
"enabled": true,
"command": ["npx", "-y", "mcp-figma-bridge"],
"environment": {
"BRIDGE_PORT": "3765",
"BRIDGE_HOST": "127.0.0.1"
}
}
}
}
```
在保存后重启 OpenCode。
---
### Cursor
**项目：** `.cursor/mcp.json`
**或全局：** `~/.cursor/mcp.json`
```json
{
"mcpServers": {
"figma-bridge": {
"command": "npx",
"args": ["-y", "mcp-figma-bridge"],
"env": {
"BRIDGE_PORT": "3765",
"BRIDGE_HOST": "127.0.0.1"
}
}
}
}
```
在编辑后重新加载 Cursor 窗口 / MCP 服务器。
---
### Windsurf / 其他“Claude 兼容”编辑器
大多数使用与 Claude Desktop 相同的格式：
```json
{
"mcpServers": {
"figma-bridge": {
"command": "npx",
"args": ["-y", "mcp-figma-bridge"],
"env": {
"BRIDGE_PORT": "3765",
"BRIDGE_HOST": "127.0.0.1"
}
}
}
}
```
---
### 通用 MCP（`.mcp.json`）
```json
{
"mcpServers": {
"figma-bridge": {
"command": "npx",
"args": ["-y", "mcp-figma-bridge"],
"env": {
"BRIDGE_PORT": "3765",
"BRIDGE_HOST": "127.0.0.1"
}
}
}
}
```
---
### Windows 注意事項
- 如果 `npx` 不在客户端的 PATH 中，请使用完整路径，例如
`C:\\Program Files\\nodejs\\npx.cmd`
- 或安装一次：`npm i -g mcp-figma-bridge` 并设置
`command` = `mcp-figma-bridge` （或 `%AppData%\\npm\\` 下的完整路径）。
- 在使用本地克隆时，请在 JSON 路径中使用正斜杠。
---
## MCP 工具（12）
| 工具 | 描述 |
|------|-------------|
| `get_bridge_status` | **预检** - 桥接服务正常？插件已连接？下一步骤（无需 Figma 选择） |
| `list_page_frames` | **从页面开始** - 顶级屏幕/框架大纲 |
| `get_file_info` | 文件名，页面；`nodeCount` 仅当 `includeNodeCount=true` |
| `get_pages` | 所有页面 |
| `get_node_tree` | 帧的树结构 `nodeId` （页面无 ID → 大纲仅限） |
| `get_selection` | 当前选择（大页面缩放 → 摘要 + 警告） |
| `get_components` | 组件和组件集 |
| `get_colors` | 按使用情况划分的纯色填充 |
| `get_fonts` | 字体系列 + 样式列表 |
| `export_node` | PNG @2x（MCP **图像** + 元数据）或 SVG；`includeBase64` / `includeDataUri` 可选 |
| `export_icons` | 批量 SVG 图标（并行，`concurrency` 默认 4） |
| `check_design_quality` | 自动命名，隐藏图层，微小文本，间距网格 |
### 超时链
| 层 | 默认值 | 角色 |
|-------|---------|------|
| 插件 UI 沙盒 | ~28s | Figma 内部每个命令 |
| 桥接服务 `POST /cmd` | ~30s | 等待插件 `/result` |
| MCP `CMD_TIMEOUT_MS` | 35s | 客户端 → 桥接服务 HTTP |
| Grok `tool_timeout_sec` | 60（推荐） | 客户端中止工具调用 |
对于大型 `export_node` / `export_icons`，请保持客户端工具超时 ≥ 60s，首选大帧的 `scale=1`，并避免 `includeDataUri` / `includeBase64` 除非需要。
工具结果为 **紧凑的 JSON** （无缩进）。截断的树结构包括 `meta.continueWith` 以便后续 `get_node_tree` 调用。`list_page_frames` 缓存约 15s（`forceRefresh=true` 以刷新）。
客户端中的工具名称通常以服务器名称为前缀，例如
`figma-bridge__list_page_frames`。
---
## 页面 vs 组件准确性
选择单个**组件/框架**通常非常准确。转储整个**页面**是一项不准确的操作：深度限制 + MCP 输出大小会截断树结构，因此模型会丢失层。
**推荐工作流（页面级）：**
1. `list_page_frames` → 选择屏幕（`likelyScreen: true` 或按名称）
2. `get_node_tree`，`nodeId=<frameId>`，`maxDepth=8`，`detail=standard`
3. 如果某个部分不完整 → 再次使用该部分的 `nodeId` 调用 `get_node_tree`
4. 可选：帧的 `export_node` PNG 进行视觉检查
避免：对整个页面使用一个 `get_node_tree` 且 `maxDepth` 较高。
---
## 每日检查清单
```text
[ ] Figma → MCP Bridge → 启动 （已连接）
[ ] MCP 客户端运行并配置了 figma-bridge 配置（npx 自动启动桥接服务）
[ ] 打开正确的 Figma 文件 / 页面
[ ] 可选：调用 `get_bridge_status` （ready=true）进行重型工具前
```
---
## 项目布局
```text
figma-mcp-bridge/
├── bin/
│ └── mcp-figma-bridge.js # npx / bin 入口
├── figma-plugin/
│ ├── manifest.json
│ ├── code.js # Figma 沙盒 - API + 工具
│ └── ui.html # 长轮询 UI
├── mcp-server/
│ ├── bridge.js # HTTP 长轮询桥接服务
│ └── index.js # MCP 标准输入输出服务器（+ 自动启动桥接服务）
├── package.json
├── claude_desktop_config.example.json
├── LICENSE
└── README.md
```
---
## 从克隆开发
```bash
git clone https://github.com/sonht113/mcp-figma-bridge.git
cd mcp-figma-bridge
node bin/mcp-figma-bridge.js plugin-path # 导入此清单到 Figma
node bin/mcp-figma-bridge.js bridge # 如果不使用MCP 自动启动桥接服务
# MCP 客户端参数：node /ABS/PATH/mcp-server/index.js
```
---
## 版本和发布
| 源 | 查找位置 |
|--------|----------------|
| 最新 npm | https://www.npmjs.com/package/mcp-figma-bridge |
| GitHub 标签 / 发布版本 | https://github.com/sonht113/mcp-figma-bridge/releases |
| 完整历史 | [CHANGELOG.md](./CHANGELOG.md) |
约定：GitHub 标签 `vX.Y.Z` == npm 版本 `X.Y.Z`。
---
## 发布（| 许可证：[MIT](https://opensource.org/licenses/MIT)
