# @gethopp/figma-mcp-bridge 中文文档

规范地址：https://npmcn.com/package/%40gethopp/figma-mcp-bridge/

版本：0\.0\.27
npm 元数据更新时间：2026-11-13T10:13:58.538Z
中文译文更新时间：2026-11-16T06:14:05.503Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40gethopp/figma-mcp-bridge
原文对照：https://npmcn.com/package/%40gethopp/figma-mcp-bridge/?lang=original
项目主页：https://github.com/gethopp/figma-mcp-bridge#readme
源码仓库：https://github.com/gethopp/figma-mcp-bridge

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：437 kB，32 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.0\.0
- 运行依赖：4 个
- 首次发布：2026-02-08T15:25:16.051Z
- 最新版本发布：2026-11-13T10:13:58.175Z
- 近 30 天下载量：13142（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：27（近 12 个月 27 个）

## 中文简介

将 Figma 插件数据连接到 AI 工具的 MCP 服务器,而不触及 API 速率限制

## 安装

```sh
npm install @gethopp/figma-mcp-bridge
```

也可以使用：`pnpm add @gethopp/figma-mcp-bridge`、`yarn add @gethopp/figma-mcp-bridge`、`bun add @gethopp/figma-mcp-bridge`

## README

# 图片MCP 桥

[![Pairing with Hopp](https://gethopp.app/git/hopp-shield.svg?ref=hopp-repo)](https://gethopp.app/)

-   [演示](https://npmcn.com/package/%40gethopp/figma-mcp-bridge/#readme-demo)
-   [快速启动](https://npmcn.com/package/%40gethopp/figma-mcp-bridge/#readme-quick-start)
-   [可用工具](https://npmcn.com/package/%40gethopp/figma-mcp-bridge/#readme-available-tools)
-   [地方发展](https://npmcn.com/package/%40gethopp/figma-mcp-bridge/#readme-local-development)
-   [结构](https://npmcn.com/package/%40gethopp/figma-mcp-bridge/#readme-structure)
-   [如何运作](https://npmcn.com/package/%40gethopp/figma-mcp-bridge/#readme-how-it-works)

  
![Figma MCP Bridge](https://raw.githubusercontent.com/gethopp/figma-mcp-bridge/main/logo.png)  

> \[注\]  
> 需要Figma桌面应用程序(macOS/Windows). Figma的浏览器版本不支持导入开发插件.

其他惊人的 Figma MCP 服务器喜欢 [图片- 内容- MCP](https://github.com/GLips/Figma-Context-MCP/) 问题之一是 [API 限制](https://github.com/GLips/Figma-Context-MCP/issues/258) 免费用户.

免费账户的限额是每月6次,是 **每个月**。 。 。 .

图片MCP 桥梁是这个问题的解决办法。 是一个插件 + MCP 服务器, 将 Figma 文档数据流到 AI 工具, 而不切入 Figma API 率限制, 所以它的 Figma MCP 对我们其余的 QQ

它支持 **多个同时连接的 Figma 文件**; 打开每个文件中的插件, 您的AI代理可以通过 `fileKey`。单文件设置工作与以前完全相同,不需要修改.

它还包括一套小的、选入的 **写入工具** 用于安全代理驱动编辑 — 见 [编辑注释](https://npmcn.com/package/%40gethopp/figma-mcp-bridge/#readme-editing-notes) 见下文.

## 演示

[使用 Figma MCP 桥在 Cursor 中构建 UI 的演示](https://youtu.be/ouygIhFBx0g)

[![Watch the video](https://img.youtube.com/vi/ouygIhFBx0g/maxresdefault.jpg)](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\. 添加图像插件

从中下载插件 [最新发布](https://github.com/gethopp/figma-mcp-bridge/releases) 页面,然后在图解 `Plugins > Development > Import plugin from manifest` 选择 `manifest.json` 从文档 `plugin/` 文件夹。 同一插件运行在Figma设计文件,Dev Mode(只读)和FigJam板.

### 3\. 开始使用

打开一个 Figma 文件, 运行插件, 并启动您的 AI 工具 。 MCP服务器会自动连接到插件.

要跨越多个文件工作,只需打开每个 Figma 文件的插件. 该桥保持所有连接活动 和你的AI代理可以瞄准其中任何一个 通过 `fileKey`。 。 。 .

如果你想知道更多 如何工作,阅读 [如何运作](https://npmcn.com/package/%40gethopp/figma-mcp-bridge/#readme-how-it-works) 节.

## 可用工具

| 工具 | 说明 |
| --- | --- |
| `list_files` | 列出所有已连接的 Figma 文件( 支持多文件工作流程) |
| `get_document` | 获取当前图像页面文档树 |
| `get_selection` | 获取 Figma 中当前选定的节点 |
| `get_node` | 通过 ID (结号格式,例如 . `4029:12345`(中文(简体) ) |
| `get_prototype_connections` | 读取节点上的原型互动及其后人 |
| `trace_prototype_flow` | 跟踪屏幕之间的原型导航 |
| `get_styles` | 获得所有本地颜料、文本、效果和网格样式 |
| `get_metadata` | 获取文件名称、页面和当前页面信息 |
| `get_design_context` | 为了解设计背景而优化了有深度限制的树 |
| `get_variable_defs` | 获取所有可变收藏、模式和值( 设计符号) |
| `get_screenshot` | 导出节点为 PNG/SVG/JPG/PDF(基础64-编码) |
| `save_screenshots` | 导出并直接保存截图到本地文件系统 |
| `get_motion_styles` | 列出所有可用的动画预设( β) |
| `get_node_motion` | 读取节点当前动画风格和属性( β) |
| `apply_animation_style` | 将预设的动画样式应用到节点(β) |
| `remove_animation_style` | 从节点(β)中删除一个应用的动画样式 |
| `apply_manual_keyframe_track` | 对节点属性( β) 应用手动密钥框架音轨 |
| `remove_manual_keyframe_track` | 从节点属性( β) 中删除手动键框音轨 |
| `set_timeline_duration` | 设定时间段以秒( β) |
| `set_node_visibility` | 显示或隐藏特定节点 |
| `set_text_content` | 替换文本节点的内容( TEXT、 FigJam 粘贴或形状标签) |
| `set_text_properties` | 补丁字体、大小、对齐、自动修改大小、颜色和文本节点/分层上的界限 |
| `set_node_properties` | 补丁常见节点属性:名称,位置,大小,能见度,不透明,角半径(单或批) |
| `set_node_constraints` | 为一个或多个相容节点设置本地图形约束( 水平/ 垂直) |
| `apply_paint_style` | 链接本地图形样式来填充或中键( 单个或批次), 保留本地样式 ID |
| `set_solid_fill` | 将节点的填充或中风取而代之的是单一固体油漆 |
| `set_gradient_fill` | 用线性/射线/角/钻石梯度来取而代之 |
| `set_effects` | 替换节点效果列表( 投放/ 内阴影, 层/ 后地模糊) |
| `set_stroke_properties` | 补丁中风重量、对齐、破损图案、盖子和加入 |
| `set_auto_layout` | 配置自动放出方向、 粘接、 间隙、 对齐、 大小、 并包接( 非区段) |
| `create_page` | 在文档中创建新页面, 可选择切换到它 |
| `create_frame` | 创建一个新框架, 选择在父框架下 |
| `create_section` | 创建一个区域——一个命名的可扩展容器(图像和图像) |
| `create_text` | 创建新文本节点 |
| `create_shape` | 创建矩形、椭圆形或行 |
| `create_shape_with_text` | 创建带有自己文本标签的 FigJam 形状( SHAPE WITH TEXT), 包括文本填充 |
| `create_image` | 从本地路径、 URL 或数据 URI 创建图像后置矩形 |
| `create_svg` | 导入原始 SVG 标记或工作空间本地 SVG 文件为可编辑矢量层 |
| `create_sticky` | 在 FigJam 中创建粘贴注释 |
| `create_connector` | 在 FigJam 创建两个节点之间的连接器, 并带有附件锚 |
| `import_html_layers` | 批量导入 html- figma 层树( JSON) 作为框架、 文本、 矩形和向量 |
| `duplicate_nodes` | 复制节点到位 |
| `duplicate_with_offset` | 复制节点并用固定的平分移动每个重复 |
| `fit_to_content` | 用可选的垫子调整孩子周围的区块大小 |
| `distribute_horizontally` | 水平差距相等的空间 3+节点(第一次/最后一次固定) |
| `distribute_vertically` | 垂直差距相等的空间3+节点(第一次/最后一次固定) |
| `align_to_grid` | 将节点位置对准给定大小的网格 |
| `place_below` | 将一个节点移动到另一个有缺口并启动/中心对齐的节点下方 |
| `place_right_of` | 将一个节点移动到另一个有缺口和启动/中心对齐的节点右侧 |
| `reparent_nodes` | 将节点移动到另一个父端 |
| `group_nodes` | 将节点列表( 共享父代码) 围入新组 |
| `ungroup_node` | 解除一个群体或框架的组合——儿童升至其父母 |
| `set_selection` | 将页面选择设置为节点ID列表( 以 Dev 模式进行的工作) |
| `scroll_and_zoom_into_view` | 设定给定节点周围的取景口( 工作在 Dev 模式) |
| `delete_nodes` | 在明确确认的情况下删除节点 |
| `run_script` | 在插件沙盒中运行插件 API JavaScript( opt- in, 参见编辑注释) |

所有工具都接受可选 `fileKey` 当多个 Figma 文件连接时参数。 使用 `list_files` 以发现连接的文件及其密钥.

### 原型笔记

-   原型工具只读取,在FigJam中不可用. 设定 `includePrototype: true` 打开 `get_node` 包括同样的相互作用.
-   反应是Figma自己的触发和动作数据,其目的地,变量和模式被解为名.
-   流程边缘列出其附件分支 `conditions` 从最外到最内( c)`null` 标记另一个分支).
-   观察 `AFTER_TIMEOUT` 值为秒(例如, `0.8` 给800毫秒.

### 编辑注释

-   只有当Figma的设计编辑器打开了插件(Dev Mode只读——它们会返回那里一个明显的错误)时,才编辑工具工作.
-   单位 **图片吉姆**,读取工具外加写出工具(`set_text_content`, (中文(简体) ), `set_text_properties`, (中文(简体) ), `set_node_properties`, (中文(简体) ), `set_solid_fill`, (中文(简体) ), `create_text`, (中文(简体) ), `create_shape`, (中文(简体) ), `create_shape_with_text`, (中文(简体) ), `create_sticky`, (中文(简体) ), `create_connector`, (中文(简体) ), `create_section`, (中文(简体) ), `duplicate_nodes`, (中文(简体) ), `duplicate_with_offset`, (中文(简体) ), `fit_to_content`, (中文(简体) ), `distribute_horizontally`, (中文(简体) ), `distribute_vertically`, (中文(简体) ), `align_to_grid`, (中文(简体) ), `place_below`, (中文(简体) ), `place_right_of`, (中文(简体) ), `delete_nodes`,...))可提供. 自动放出和运动/活化工具返回 FigJam 中一个明显的错误.
-   `set_text_content` 编号 : `set_text_properties` 直接编辑一个TEXT节点的内容,或者一个FigJam STICKY / SHAPE WITH TEXT节点的文本子层. 对齐和自动调整的大小是TEXT-node-只——它们返回粘接物和形状上一个明显的错误(x/y/width/hight仍然适用于包含的节点).
-   `set_node_properties` 接受其中之一 `nodeId` 或一个 `nodeIds` 数组将同样的属性更改应用到一个调用中的几个节点.
-   `apply_paint_style` 接受 `nodeId` 或者说 `nodeIds`,当地 `styleId` 从 `get_styles`,以及 `target` (单位:千美元)`fill` 默认,或 `stroke`) (中文(简体) ). 它只在Figma Design中工作,应用了本土风格(在所选目标上替换颜料),并报告链接的ID;一组报告成功和每个节点出错. `get_node` 曝光情况 `styles.fillStyleId` 财务报告和审定财务报表 `styles.strokeStyleId` 用于独立核查(空ID表示无链接); `mixed` 表示整个节点的属性有混合值. 它不导入共享库或样式单个文本区域 .
-   `set_node_constraints` 接受 `nodeId` 或者说 `nodeIds` 与 `horizontal` 和(或) `vertical` (单位:千美元)`MIN`, (中文(简体) ), `MAX`, (中文(简体) ), `CENTER`, (中文(简体) ), `STRETCH`, (中文(简体) ), `SCALE`) (中文(简体) ). `MIN` 表示左/ 托普, `MAX` 右/下,和 `STRETCH` 左下/ 右下角( R) 。 未指明的轴被保存. 它需要Figma框架、组件或实例中的节点; 自动布局子必须使用绝对定位。 在 FigJam 和 Dev Mode 中无法使用。 答复中报告了以前受到的限制.
-   `set_auto_layout` 目标框架; 分区节点在 Figma 的 API 中没有自动放出, 并返回一个明显的错误 .
-   `fit_to_content` 仅仅在分区节点上工作(Figma的API不显示其他容器的等同性):它转移儿童,所以他们的边框开始于 `padding` 并调整区域大小为 bbox + 2xpading.
-   当前用户必须拥有编辑目标文件的权限.
-   `delete_nodes` 被故意关在后面 `confirm: true`。 。 。 .
-   `run_script` 在打开的文件中执行任意的 JavaScript, 因此它关闭, 除非 MCP 服务器使用 `FIGMA_BRIDGE_ENABLE_RUN_SCRIPT=1` (见 [启用 `run_script`](https://npmcn.com/package/%40gethopp/figma-mcp-bridge/#readme-enabling-run_script)) (中文(简体) ). 代码是一个 async 函数的正体, 与 `figma` 范围及其影响 `return` 值必须是 JSON 序列可操作 。 调用代码 `.remove()` 被拒绝,除非 `allowRemove: true` ; 防止意外删除, 而不是安全边界。 服务器在3分钟后停止等待,但一个被困在循环中的脚本让插件一直忙到关闭. 在法格玛和法格吉姆工作.
-   文本编辑在应用新内容之前自动加载目标文本节点目前使用的字体.
-   新建文本节点默认为 `Inter Regular` 除非提供了字体.
-   `create_image` 读取相对于 MCP 服务器工作目录的本地路径,除非您通过绝对路径.
-   `create_svg` 接受原始数据 `<svg>` 标记或 MCP 服务器工作目录内的本地 SVG 路径。 SVG的有效载荷限于2个米B.
-   `import_html_layers` 使用 JSON 文件 [html- 图片](https://github.com/sergcen/html-to-figma)浏览器 `htmlToFigma()`。路径相对于 MCP 服务器工作目录解决,必须留在其中,即使绝对。 所有东西都落在一个包装框里 反应报告 `layerCount` 反对 `expectedLayerCount` 因此,部分进口是可见的.
-   `create_page` 返回新页面的 ID —— 以 `parentId` 改为 `create_frame` 编号 : `create_text` 编号 : `create_shape` 编号 : `create_image` 到该页面的作者内容而不切换编辑器.

### 启用 `run_script`

`run_script` 默认关闭。 打开它,加 `FIGMA_BRIDGE_ENABLE_RUN_SCRIPT` 到服务器 `env` 在您的 MCP 配置中重新启动您的 AI 工具 :

```json
{
  "figma-bridge": {
    "command": "npx",
    "args": ["-y", "@gethopp/figma-mcp-bridge"],
    "env": {
      "FIGMA_BRIDGE_ENABLE_RUN_SCRIPT": "1"
    }
  }
}
```

如果多个AI工具同时运行桥,则在其每个配置中设置变量. 一次只和菲格玛一个桥段的谈话 却拒绝 `run_script` 除非是从变量开始的.

### 你可以构建什么

在当前写出表层的情况下,一个代理可以在一个新的空法格玛文件中构建一个基本的幻灯片甲板:创建幻灯片框架,样式标题和体型副本,为卡片和分牌设定矩形/椭圆/行,复制幻灯片模板,将内容重新显示到正确的框中,并调整常见的几何/视觉属性——包括固体/渐变颜料,阴影和模糊,中风几何和自动放出配置.

目前版本是有意限制的——没有组件/插件,没有变量/样式的作者,没有分块文本样式,还没有矢量布尔操作.

## 地方发展

此还原使用 [阿宝](https://bun.sh/) 作为其软件包管理器和脚本运行器。 没有的话先安装.

#### 1\. 克隆此存储器

```bash
git clone git@github.com:gethopp/figma-mcp-bridge.git
```

#### 2\. 安装根工具

安装根依赖性一次 。 这个是哈斯基的 `prepare` 脚本,它安装了 Git 预承诺的钩子,格式将文件与 Pretier 相接而成.

```bash
cd figma-mcp-bridge && bun install
```

#### 3\. 建立服务器

```bash
cd server && bun install && bun run build
```

#### 4\. 构建插件

```bash
cd plugin && bun install && bun run build
```

#### 5\. 将 MCP 服务器添加到您最喜欢的 AI 工具中

对于本地开发,请在您的 AI 工具的 MCP 配置中添加以下内容:

```json
{
  "figma-bridge": {
    "command": "node",
    "args": ["/path/to/figma-mcp-bridge/server/dist/index.js"]
  }
}
```

### 代码样式

Repo 格式化为 [高级](https://prettier.io/) (配置为 `.prettierrc`) (中文(简体) ). 一个Husky预承诺钩跑 `lint-staged`,只格式化您的已上演的文件,所以承诺自动保留格式化。 您也可以手动操作 :

```bash
bun run format        # format the whole repo
bun run format:check  # verify formatting without writing (useful in CI)
```

## 结构

```
Figma-MCP-Bridge/
├── plugin/   # Figma plugin (TypeScript/React)
└── server/   # MCP server (TypeScript/Node.js)
    └── src/
        ├── index.ts      # Entry point
        ├── bridge.ts     # WebSocket bridge to Figma plugin
        ├── leader.ts     # Leader: HTTP server + bridge
        ├── follower.ts   # Follower: proxies to leader via HTTP
        ├── node.ts       # Dynamic leader/follower role switching
        ├── election.ts   # Leader election & health monitoring
        ├── tools.ts      # MCP tool definitions
        └── types.ts      # Shared types
```

## 如何运作

Figma MCP桥有两个主要部分:

### 1\. 图片插件

Figma插件是Figma MCP桥的用户界面. 您可以在 Figma 文件内运行您想要使用 MCP 服务器, 以及它负责获取您需要的所有信息 .

### 2\. MCP服务器

MCP服务器是Figma MCP桥的核心. 它维持一个由WebSocket键入的WebSocket连接的注册 `fileKey`,因此可以同时连接多个 Figma 文件。 服务器负责:

-   处理一个或多个 Figma 插件中的 WebSocket 连接
-   运行工具调用正确的文件 `fileKey`
-   向AI客户端转发回复
-   处理领导者选举(因为我们一次只能有一个WS连接到一个MCP服务器)

头儿听 `127.0.0.1` 只有这个 它的端点没有认证,所以网络上的其他机器一定不能到达. 如果插件运行在另一个主机上( 例如, MCP 服务器运行在 VM 或容器中), 设置 `FIGMA_BRIDGE_HOST=0.0.0.0` (或 `::`)在MCP服务器环境中. 只在您信任的网络上使用 .

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                           FIGMA (Desktop app)                               │
│  ┌───────────────────────────────────────────────────────────────────────┐  │
│  │                         Figma Plugin                                  │  │
│  │                    (TypeScript/React)                                 │  │
│  └───────────────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────────┘
                                      │
                                      │ WebSocket
                                      │ (ws://localhost:1994/ws)
                                      ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                          PRIMARY MCP SERVER                                 │
│                         (Leader on :1994)                                   │
│  ┌─────────────────────────────────────────────────────────────────────┐    │
│  │  Bridge                                    Endpoints:               │    │
│  │  • Manages WebSocket conn                  • /ws    (plugin)        │    │
│  │  • Forwards requests to plugin             • /ping  (health)        │    │
│  │  • Routes responses back                   • /rpc   (followers)     │    │
│  └─────────────────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────────────────┘
                           ▲                              ▲
                           │ HTTP /rpc                    │ HTTP /rpc
                           │ POST requests                │ POST requests
                           │                              │
         ┌─────────────────┴───────────┐    ┌─────────────┴───────────────┐
         │    FOLLOWER MCP SERVER 1    │    │    FOLLOWER MCP SERVER 2    │
         │                             │    │                             │
         │  • Pings leader /ping       │    │  • Pings leader /ping       │
         │  • Forwards tool calls      │    │  • Forwards tool calls      │
         │    via HTTP /rpc            │    │    via HTTP /rpc            │
         │  • If leader dies →         │    │  • If leader dies →         │
         │    attempts takeover        │    │    attempts takeover        │
         └─────────────────────────────┘    └─────────────────────────────┘
                    ▲                                      ▲
                    │                                      │
                    │ MCP Protocol                         │ MCP Protocol
                    │ (stdio)                              │ (stdio)
                    ▼                                      ▼
         ┌─────────────────────────────┐    ┌─────────────────────────────┐
         │      AI Tool / IDE 1        │    │      AI Tool / IDE 2        │
         │      (e.g., Cursor)         │    │      (e.g., Cursor)         │
         └─────────────────────────────┘    └─────────────────────────────┘
```

## 常见问题

### @gethopp/figma-mcp-bridge 是什么？

将 Figma 插件数据连接到 AI 工具的 MCP 服务器,而不触及 API 速率限制

### 如何安装 @gethopp/figma-mcp-bridge？

在项目目录运行 npm install @gethopp/figma-mcp-bridge，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 figma-mcp-bridge，可以用 npx figma-mcp-bridge 直接运行。

### @gethopp/figma-mcp-bridge 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @gethopp/figma-mcp-bridge 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @gethopp/figma-mcp-bridge 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @gethopp/figma-mcp-bridge 可以商用吗？

@gethopp/figma-mcp-bridge 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @gethopp/figma-mcp-bridge 的下载量有多少？

根据 npm 官方下载统计，@gethopp/figma-mcp-bridge 在 2026/10/17 – 2026/11/15 这 30 天内被下载 13,142 次，日均约 438 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @gethopp/figma-mcp-bridge 还在维护吗？

最新版本 0\.0\.27 发布于 2026/11/13（2 天前）；至今共发布 27 个版本，其中过去 12 个月发布了 27 个；首次发布于 2026/02/08。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

