内容
# Figma MCP Bridge
[](https://gethopp.app)
- [演示](#演示)
- [快速开始](#快速开始)
- [可用工具](#可用工具)
- [设计令牌](#设计令牌)
- [工程评审指南](#工程评审指南)
- [开发文档](#开发文档)
- [贡献](#贡献)
- [本地开发](#本地开发)
- [结构](#结构)
- [工作原理](#工作原理)
<br/>
<img src="https://raw.githubusercontent.com/gethopp/figma-mcp-bridge/main/logo.png" alt="Figma MCP Bridge" align="center" />
<br/>
其他优秀的 Figma MCP 服务器，如 [Figma-Context-MCP](https://github.com/GLips/Figma-Context-MCP/)，存在一个问题：免费用户的 [API 请求限制](https://github.com/GLips/Figma-Context-MCP/issues/258)。
免费帐户的限制为每月 6 次请求，是的，**每月仅限 6 次**。
Figma MCP Bridge 是为了解决这个问题而设计的。它是一个本地的 Figma 插件 + MCP 服务器桥接器，通过 WebSocket 将当前打开的 Figma 文件流式传输到 AI/MCP 客户端，避免了 Figma REST API 的速率限制 — 为我们提供 Figma MCP 服务 ✊
## 演示
[观看使用 Figma MCP Bridge 构建 UI 的演示](https://youtu.be/ouygIhFBx0g)
[](https://youtu.be/ouygIhFBx0g)
## 快速开始
### 1. 将 MCP 服务器添加到您喜欢的 AI 工具中
将以下内容添加到您的 AI 工具的 MCP 配置中（例如 Cursor、Windsurf、Claude Desktop）：
```json
{
"figma-bridge": {
"command": "npx",
"args": ["-y", "@gethopp/figma-mcp-bridge"]
}
}
```
就这样 — 无需下载或安装二进制文件。
### 2. 添加 Figma 插件
从 [最新发布](https://github.com/gethopp/figma-mcp-bridge/releases) 页面下载插件，然后在 Figma 中前往 `插件 > 开发 > 从清单导入插件`，并选择 `plugin/` 文件夹中的 `manifest.json` 文件。
### 3. 开始使用 🎉
打开一个 Figma 文件，运行插件，然后开始提示您的 AI 工具。MCP 服务器将自动连接到插件。
如果您想了解更多关于其工作原理的信息，请阅读 [工作原理](#工作原理) 部分。
## 可用工具
| 工具 | 描述 |
|------|-------------|
| `list_files` | 列出当前连接到桥接器的 Figma 文件；使用返回的 `fileKey` 来定位特定文件 |
| `get_document` | 获取当前 Figma 页面文档树 |
| `get_selection` | 获取 Figma 中当前选定的节点 |
| `get_node` | 通过 ID 获取特定的 Figma 节点（冒号格式，例如 `4029:12345`） |
| `get_styles` | 获取所有本地绘制、文本、效果和网格样式 |
| `get_metadata` | 获取文件名称、页面和当前页面信息 |
| `get_design_context` | 获取优化的树以理解设计上下文 |
| `get_variable_defs` | 获取所有变量集合、模式和值（设计令牌） |
| `get_design_tokens` | 从本地变量和样式中获取标准化的设计令牌，带有 AI 友好的路径、来源、模式和摘要计数 |
| `get_token_usage` | 扫描选择、当前页面或特定节点，并通过绑定、样式或精确值匹配将节点属性映射到令牌 |
| `audit_design_tokens` | 只读审核令牌覆盖率和一致性；根据令牌图和用法映射返回问题和建议 |
| `propose_design_tokens` | 基于重复的未绑定值和重复令牌值的只读令牌提案工作流程 |
| `create_design_tokens` | 从审查的令牌列表中创建本地变量/样式；默认为干运行，只有在 `dryRun=false` 时才写入 |
| `apply_tokens` | 将变量或样式绑定到匹配的节点属性；默认为干运行，只有在 `dryRun=false` 时才写入 |
| `export_design_tokens` | 将标准化的令牌导出为 JSON、DTCG JSON、CSS 变量或 Tailwind 主题令牌，而无需修改 Figma |
| `get_screenshot` | 将节点导出为 PNG/SVG/JPG/PDF（base64 编码） |
| `save_screenshots` | 将截图直接导出并保存到本地文件系统 |
| `create_frame` | 在当前页面上创建一个框架 |
| `create_component` | 在当前页面上创建一个一流的 Figma 组件 |
| `create_instance` | 通过 `componentId` 从本地组件创建实例 |
| `combine_as_variants` | 将两个或多个本地组件组合成一个原生 Figma 组件集/变体节点 |
| `set_variant_properties` | 在组件集内的变体组件上设置或更新 `State=Hover`、`Size=Large` 等 |
| `manage_component_properties` | 添加、编辑或删除组件或组件集上的组件属性定义 |
| `set_component_properties` | 通过 Figma `setProperties(...)` 在实例上设置变体/组件属性值 |
| `set_exposed_instance` | 切换嵌套实例是否暴露给包含的组件/组件集 |
| `create_text` | 在当前页面上创建一个文本节点 |
| `create_rectangle` | 在当前页面上创建一个矩形 |
| `append_children` | 将现有的子节点重新父节点到父节点下 |
| `find_nodes` | 通过 ID、名称、键或父节点在当前页面上查找节点 |
| `set_position` | 设置节点位置 |
| `set_size` | 设置节点大小 |
| `set_fills` | 使用支持的实心涂料设置节点填充 |
| `set_strokes` | 使用支持的实心涂料设置节点描边 |
| `set_corner_radius` | 设置统一的圆角半径 |
| `set_text_content` | 设置文本内容 |
| `set_text_style` | 设置文本样式 |
| `set_layout_mode` | 设置自动布局模式 |
| `set_padding` | 设置自动布局填充 |
| `set_item_spacing` | 设置自动布局项目间距 |
| `set_node_name` | 重命名现有的 Figma 节点 |
| `rename_node` | `set_node_name` 的别名 |
| `delete_node` | 删除节点 |
| `batch_mutation` | 按顺序执行最多 100 次写入操作，并使用临时引用进行多步骤生成 |
写入工具的作用范围故意限制在当前页面和 Figma 变体的确定性子集，以便 AI 驱动的编辑更容易验证和更安全地自动化。组件支持创建组件节点、创建本地 `componentId` 实例、将两个或多个现有本地组件组合成一个原生 `COMPONENT_SET`，通过 `combine_as_variants`（`componentIds`，可选 `parentId`、`name`、`x`、`y`、`key`），管理组件集内组件的变体名称/属性，管理组件属性定义，设置实例组件属性，并切换暴露的嵌套实例。`set_variant_properties` 通过将目标组件重命名为 Figma 的 `Property=Value` 语法来更新变体；`manage_component_properties` 遵循 Figma 插件 API 限制（例如，不支持删除 `VARIANT` 定义）。`set_exposed_instance` 还遵循 Figma 的原生资格规则：目标必须是组件/组件集内的合格嵌套实例，可能需要暴露的嵌套实例或具有组件属性引用的子节点。远程库导入通过组件键在此阶段仍不在范围内。
所有 Figma 支持的工具都接受一个可选的 `fileKey`。当恰好连接一个插件实例时，工具保持向后兼容，可以省略 `fileKey`。当连接多个 Figma 文件/插件实例时，如果调用者提供 `fileKey`，则工具调用失败；首先调用 `list_files`，然后传递所需文件的 `fileKey` 以读取、截图、令牌和写入工具。未保存的 Figma 文件使用插件会话备用键，以便同时打开的“未标题”文件仍然可以区分。
在 `batch_mutation` 中，临时引用必须使用 `tmp:` 前缀，例如 `ref: "tmp:modal"` 和 `nodeId: "tmp:modal"`。裸标签如 `"modal"` 被视为字面节点 ID，不会解析为批量引用。
## 设计令牌
Figma MCP Bridge 以分层工作流公开设计系统数据：
1. **原始来源**：`get_styles` 返回本地绘制、文本、效果和网格样式。`get_variable_defs` 返回 Figma 变量集合、模式、值和别名。
2. **标准化图**：`get_design_tokens` 将变量和样式组合成稳定的 AI 友好令牌路径，例如 `color.brand.primary`，同时保留每个令牌的 `source`（`variable` 或 `style`）和模式感知值。
3. **用法和审核**：`get_token_usage` 扫描当前选择、当前页面或显式 `nodeIds`，并将匹配项分类为 `boundVariable`、`style`、`exactValue` 或 `none`。`audit_design_tokens` 使用该用法映射来报告覆盖率、未绑定用法、仅精确值匹配、重复值、未知组、空扫描和未使用令牌。
4. **提案和导出**：`propose_design_tokens` 在不写入 Figma 的情况下建议令牌候选。`export_design_tokens` 将标准化令牌图序列化为 JSON、DTCG JSON、CSS 变量或 Tailwind 主题令牌。
5. **先干运行再写入**：`create_design_tokens` 和 `apply_tokens` 默认先进行干运行。只有当调用者显式传递 `dryRun=false` 时，它们才会修改 Figma 文件。
使用只读图、用法、审核、提案和导出工具进行设计系统分析。将 `create_design_tokens` 和 `apply_tokens` 视为写入工作流：在进行实际的 Figma 更改之前，请先查看干运行计划，然后选择目标集合、节点和冲突策略。有关完整的令牌工具矩阵，请参见 [docs/design-token-tools.md](./docs/design-token-tools.md)。
## 工程评审指南
使用 [ENGINEERING_REVIEW_GUIDELINES.md](./ENGINEERING_REVIEW_GUIDELINES.md) 作为手动 MCP 工具开发和代码审查的团队基准。它定义了模块边界、工具类别、模式规则、写入操作安全边界、手动验证步骤、PR 检查清单、问题严重性级别和设计令牌特定约束。它是人类工程和评审标准，而不是 AI 客户端用法指南。
## 开发文档
- [docs/design-token-tools.md](./docs/design-token-tools.md)：令牌图、用法、审核、提案、干运行写入和导出工作流。
- [docs/development-workflow.md](./docs/development-workflow.md)：本地服务器/插件设置、验证命令、Figma 插件导入和常见故障排除。
- [docs/multi-file-routing.md](./docs/multi-file-routing.md)：多文件/插件实例路由行为、`list_files`、`fileKey` 和实时验证检查清单。
- [skills/README.md](./skills/README.md)：存储库本地代理技能，涵盖实用 MCP 工具选择、安全、截图、写入、令牌和调试工作流。
## 贡献
参见 [CONTRIBUTING.md](./CONTRIBUTING.md)，了解 Conventional Commit 范围、发布版本语义和语义发布干运行指令。
## 本地开发
#### 1. 在本地克隆此存储库
```bash
git clone git@github.com:gethopp/figma-mcp-bridge.git
```
#### 2. 构建服务器
```bash
cd server && npm install && npm run build
```
#### 3. 构建插件
```bash
cd plugin && bun install && bun run build
```
如果 `bun` 不可用，也可以使用 npm 构建插件：
```bash
cd plugin && npm install && npm run build
```
#### 4. 将 MCP 服务器添加到您喜欢的 AI 工具中
在本地开发中，将以下内容添加到您的 AI 工具的 MCP 配置中：
```json
{
"figma-bridge": {
"command": "node",
"args": ["/path/to/figma-mcp-bridge/server/dist/index.js"]
}
}
```
## 验证
在打开 PR 之前，从存储库根目录运行目标本地检查：
```bash
cd server && npm test
cd ../plugin && npm run build
npm test
```
`server` 测试编译 MCP 服务器并验证多文件路由/关闭行为以及 `fileKey` 模式覆盖。
`plugin` 测试编译插件测试构建并运行写入和设计令牌覆盖：写入操作、令牌图、用法映射、审核、提案、创建、应用和导出。
## 结构
```text
Figma-MCP-Bridge/
|-- plugin/ # Figma 插件（TypeScript/React）
| `-- src/
| |-- ui/ # Figma 插件 UI
| `-- main/
| |-- code.ts # 插件运行时入口点和 RPC 调度
| |-- serializer.ts # 读取节点/样式序列化
| `-- write.ts # 写入变异引擎和批量执行
`-- server/ # MCP 服务器（TypeScript/Node.js）
`-- src/
|-- index.ts # 入口点
|-- bridge.ts # Figma 插件的 WebSocket 桥接器
|-- leader.ts # 领导者：HTTP 服务器 + 桥接器
|-- follower.ts # 跟随者：通过 HTTP 将请求代理到领导者
|-- node.ts # 动态领导者/跟随者角色切换
|-- election.ts # 领导者选举和健康监测
|-- schema.ts # 读取/写入工具输入的 Zod 模式
|-- tools.ts # MCP 工具注册用于读取/写入操作
`-- types.ts # 共享传输类型
```
## 工作原理
Figma MCP Bridge 有两个主要组件：
### 1. Figma 插件
Figma 插件是 Figma MCP Bridge 的用户界面。您在要使用 MCP 服务器的 Figma 文件中运行此插件，它负责获取您需要的所有信息。
### 2. MCP 服务器
MCP 服务器是 Figma MCP Bridge 的核心。当 Figma 插件通过 WebSocket 连接到 MCP 服务器时，MCP 服务器负责：
- 处理来自 Figma 插件的 WebSocket 连接
- 将工具调用转发到 Figma 插件
- 将响应路由回 Figma 插件
- 处理领导者选举（因为我们一次只能与一个 MCP 服务器建立一个 WebSocket 连接）
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ Figma（浏览器） │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ Figma 插件 │ │
│ │ （TypeScript/React） │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
│
│ WebSocket
│ （ws://localhost:1994/ws）
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ 主 MCP 服务器 │
│ （领导者 on :1994） │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ 桥接器 端点： │ │
│ │ • 管理 WebSocket 连接 • /ws （插件） │ │
│ │ • 将请求转发到插件 • /ping （健康检查） │ │
│ │ • 将响应路由回 • /rpc （跟随者） │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
▲ ▲
│ HTTP /rpc │ HTTP /rpc
│ POST 请求 │ POST 请求
│ │
┌─────────────────┴───────────┐ ┌─────────────┴───────────────┐
│ 跟随者 MCP 服务器 1 │ │ 跟随者 MCP 服务器 2 │
│ │ │ │
│ • Ping 领导者 /ping │ │ • Ping 领导者 /ping │
│ • 将工具调用转发 │ │ • 将工具调用转发 │
│ 通过 HTTP /rpc │ │ 通过 HTTP /rpc │
│ • 如果领导者死亡 → │ │ • 如果领导者死亡 → │
│ 尝试接管 │ │ 尝试接管 │
└─────────────────────────────┘ └─────────────────────────────┘
▲ ▲
│ │
│ MCP 协议 │ MCP 协议
│ （stdio） │ （stdio）
▼ ▼
┌─────────────────────────────┐ ┌─────────────────────────────┐
│ AI 工具/IDE 1 │ │ AI 工具/IDE 2 │
│ （例如，Cursor） │ │ （例如，Cursor） │
└─────────────────────────────┘ └─────────────────────────────┘
```
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器