内容
<a id="readme-top"></a>
<div align="center">
# Figma 代理 MCP
**通过 MCP 实现 AI 代理的实时 Figma 访问。**
无需 REST API 令牌，无速率限制，无过时导出。
[![构建][build-shield]][build-url]
[![节点][node-shield]][node-url]
[![MCP][mcp-shield]][mcp-url]
[![Figma 插件][figma-shield]][figma-url]
[报告 Bug][issues-url] · [请求功能][issues-url]
</div>
---
## 为什么存在
现有的从 AI 代理到 Figma 文件的所有路径都通过 REST API：生成令牌，尊重速率限制，并读取可能已经过时的文件版本。该项目走了一条不同的路线 — 一个在 Figma Desktop 内运行的插件，通过本地代理桥接到您的代理。
| | Figma REST API | Figma 代理 MCP |
|---|---|---|
| 认证 | 个人访问令牌 | API 密钥（运行时，自动生成） |
| 速率限制 | 是，按令牌 | 无 |
| 数据新鲜度 | 最后保存的版本 | 实时文档，包括未保存的编辑 |
| 写访问 | 否（仅限只读端点） | 是 — 文本内容，填充，可见性，几何形状 |
| 选择感知 | 否 | 是 — 读取当前选择 |
连接到此服务器的代理可以读取设计令牌，提取 CSS，导出资产，审核复制，并写入文本内容 — 所有这些都针对 Figma Desktop 中当前打开的文件。
<details>
<summary>目录</summary>
- [为什么存在](#为什么存在)
- [快速入门](#快速入门)
- [架构](#架构)
- [前提条件](#前提条件)
- [安装](#安装)
- [连接 AI 工具](#连接-ai-工具)
- [使用捆绑的技能进行切片](#使用捆绑的技能进行切片)
- [配置](#配置)
- [工具参考](#工具参考)
- [贡献](#贡献)
</details>
---
## 快速入门
从克隆到连接代理，耗时 60 秒：
```bash
# 1. 启动服务器
docker compose up -d
# → 在 mcp-server 日志中打印 API 密钥（首次启动时自动生成）
# 2. 构建并加载插件（一次）
cd plugin && npm install && npm run build
# → Figma Desktop：插件 → 开发 → 从清单导入插件
# → 选择 plugin/manifest.json，运行插件
# → 将步骤 1 日志中的 ws://... URL 粘贴到代理 URL 字段，点击连接
# 3. 连接您的代理（使用步骤 1 中的相同 apiKey）
claude mcp add figma --transport http "http://localhost:3001/mcp?apikey=abc123"
```
需要新的密钥时？ `curl http://localhost:3001/generate-apikey` 返回一个新鲜的密钥 + 一个可以直接粘贴的 URL。
询问您的代理调用 `get_metadata` — 如果它返回您的文件名，您就已经联网了。
<p align="right">(<a href="#readme-top">返回顶部</a>)</p>
## 架构
```
AI 代理（Claude，Cursor，Windsurf，...）
│
│ 流式 HTTP（MCP 协议）
▼
┌─────────────────────────────────┐
│ mcp-server :3001 │ 工具注册 · RPC 翻译 · 响应处理
└─────────────┬───────────────────┘
│ HTTP POST /rpc
▼
┌─────────────────────────────────┐
│ websocket 代理 :3000 │ 插件连接管理器 · apiKey 命名空间路由
└─────────────┬───────────────────┘
│ WebSocket
▼
┌─────────────────────────────────┐
│ Figma 插件 │ 在 Figma Desktop 中运行 · 执行插件 API 调用
└─────────────┬───────────────────┘
│ 插件 API
▼
实时 Figma 文件
```
<p align="right">(<a href="#readme-top">返回顶部</a>)</p>
## 先决条件
- **Node.js 22+** — 用于本地开发
- **Docker + Docker Compose** — 用于容器化部署
- **Figma Desktop** — 插件需要桌面插件 API（不支持浏览器）
<p align="right">(<a href="#readme-top">返回顶部</a>)</p>
## 安装
### 选项 A — Docker（推荐）
```bash
docker compose up
```
在您的环境中设置 `API_KEY`（预共享密钥）或 `MCP_PUBLIC_URL`（远程访问）— 参见 [配置](#配置)。
### 选项 B — 本地
```bash
cd websocket && npm install && npm run dev
cd mcp-server && npm install && npm run dev
```
### Figma 插件
构建一次，然后加载到 Figma Desktop：
```bash
cd plugin && npm install && npm run build
```
1. 打开 Figma Desktop
2. **插件 → 开发 → 从清单导入插件**
3. 选择 `plugin/manifest.json`
4. 运行插件 — 连接状态指示器变为绿色
插件会自动重新连接，并在会话之间保持代理 URL。
<p align="right">(<a href="#readme-top">返回顶部</a>)</p>
## 连接 AI 工具
MCP 服务器在 `http://localhost:3001/mcp` 处使用 **流式 HTTP** 进行通信。所有连接都需要一个 `apikey` 查询参数 — 服务器在启动时打印一个，或者使用 `curl http://localhost:3001/generate-apikey` 生成一个新的。
> 连接前：两个服务器必须运行，Figma 插件必须在 Figma Desktop 中激活（绿色指示器）。如果没有插件，客户端连接正常，但每次工具调用都会返回 *"没有连接 Figma 插件。请在 Figma 中运行插件。"*
### Claude 代码
```bash
claude mcp add figma --transport http "http://localhost:3001/mcp?apikey=YOUR_API_KEY"
```
使用 `claude mcp list` 验证 — `figma` 应该报告 ✔ 已连接。
### Claude 桌面版
编辑您操作系统的配置文件：
| 操作系统 | 路径 |
|---|---|
| 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": {
"url": "http://localhost:3001/mcp?apikey=YOUR_API_KEY"
}
}
}
```
保存后重启 Claude Desktop — MCP 服务器仅在启动时加载。连接后，`figma` 服务器出现在工具（🔨）图标下。
### Cursor
创建或编辑 `.cursor/mcp.json` 在您的项目中（或 `~/.cursor/mcp.json` 用于所有项目）：
```json
{
"mcpServers": {
"figma": {
"url": "http://localhost:3001/mcp?apikey=YOUR_API_KEY"
}
}
}
```
然后在 **设置 → MCP** 下启用服务器 — 它应该列出可用的工具。
### Windsurf
编辑 `~/.codeium/windsurf/mcp_config.json`:
```json
{
"mcpServers": {
"figma": {
"serverUrl": "http://localhost:3001/mcp?apikey=YOUR_API_KEY"
}
}
}
```
保存后刷新 **设置 → Cascade → MCP 服务器**。
### 远程或隧道服务器
要从另一台机器访问服务器，请通过隧道（Cloudflare Tunnel，ngrok，Tailscale Funnel，...）公开 3001 端口，然后将客户端指向公共 URL：
```bash
claude mcp add figma --transport http "https://your-tunnel.example.com/mcp?apikey=YOUR_API_KEY"
```
两个服务器端设置在这里很重要（参见 [配置](#配置)）：
- **`API_KEY`** — 在公开可访问的服务器上始终通过 env var 设置；如果没有它，任何拥有 URL 的人都可以读取和修改您的打开的 Figma 文件。
- **`MCP_PUBLIC_URL`** — 设置为隧道 URL，以便导出工具返回的资产 `downloadUrl` 可以从代理的机器访问。
### 烟雾测试
无论使用哪个客户端，请询问代理调用 `get_metadata`。正确的设置会返回打开的文件名、页面列表和文件密钥。如果失败：
| 症状 | 可能的原因 |
|---|---|
| 连接被拒绝 | 3001 上的 MCP 服务器未运行 |
| 401 未授权 | 缺少或无效的 `apikey` 查询参数 |
| "没有连接 Figma 插件" | 插件未运行，或插件和客户端之间的 API 密钥不匹配 |
<p align="right">(<a href="#readme-top">返回顶部</a>)</p>
## 使用捆绑的技能进行切片
对于设计到代码的切片，不要手动驱动工具 — 此存储库附带一个 `figma-slice` 技能，协调整个管道（参考截图，规范提取，资产导出，HTML 构建和 ≥95% 的视觉保真度门控）。使用以下命令安装：
```bash
npx skills add alfianyusufabdullah/figma-proxy-mcp
```
然后从您的代理调用它，带有一个节点 ID，或者不带任何节点 ID 来切片当前的 Figma 选择。
<p align="right">(<a href="#readme-top">返回顶部</a>)</p>
## 配置
| 变量 | 默认值 | 描述 |
|---|---|---|
| `PROXY_URL` | `http://localhost:3000` | WebSocket 代理地址，由 MCP 服务器使用 |
| `MCP_PORT` | `3001` | MCP 服务器的监听端口 |
| `API_KEY` | 自动生成 | 用于多路复用的预共享 API 密钥。如果未设置，在启动时自动生成。调用 `GET /generate-apikey` 进行轮换。 |
| `MCP_PUBLIC_URL` | `http://localhost:3001` | MCP 服务器的公共基准 URL。用于构造导出工具返回的 `downloadUrl` 值。必须设置为隧道的 URL，以便在远程访问服务器时，返回的链接可从代理的机器访问。 |
<p align="right">(<a href="#readme-top">返回顶部</a>)</p>
## 工具参考
节点 ID 接受内部冒号格式 (`2650:516`) 和 Figma 分享 URL 中找到的连字符格式 (`2650-516`)。所有工具都接受一个可选的 `fileKey` 来定位特定的打开文件；如果只连接了一个文件，请省略它。
### 文档和节点检查
| 工具 | 关键参数 | 描述 |
|---|---|---|
| `get_document` | `depth`, `maxNodes` | 当前页面的完整节点树 |
| `get_selection` | — | 当前选定的节点 |
| `get_node` | `nodeId`, `maxNodes` | 获取单个节点及其子树。增加 `maxNodes`（高达 5000）以获取更深的树。 |
| `get_node_full` | `nodeId` | 类似 `get_node` 但自动重试并增加 `maxNodes` 直到返回完整的树 — 不截断 |
| `get_slice_spec` | `nodeId` | 一次调用切片包：完整的节点树 + 布局规范 + 所有 SVG 矢量数据 |
| `get_design_context` | `nodeIds`, `depth`, `maxNodes` | 一个或多个节点的深度有限快照，为 AI 上下文窗口优化 |
| `get_metadata` | — | 文件名，页面列表，当前页面，文件密钥 |
### CSS 和布局
| 工具 | 关键参数 | 描述 |
|---|---|---|
| `get_css` | `nodeId` | CSS 属性：尺寸，弹性，颜色，填充，边框半径 |
| `get_layout_spec` | `nodeId` | 完整的自动布局规范 — 方向，间隙，填充，对齐方式，尺寸模式 |
| `get_responsive_behavior` | `nodeId` | 约束，增长标志，最小/最大尺寸 |
| `get_corner_radii` | `nodeId` | 每个角的半径和圆角因子 |
| `get_stroke_spec` | `nodeId` | 每侧的笔画权重，虚线图案，帽和连接样式 |
| `get_effect_spec` | `nodeId` | 带有完整参数的阴影和模糊效果 |
| `get_styles` | — | 所有本地绘制，文本，效果和网格样式 |
### 组件和设计令牌
| 工具 | 关键参数 | 描述 |
|---|---|---|
| `get_component_properties` | `nodeId` | 属性定义，变体道具，开发模式状态 |
| `get_instance_overrides` | `nodeId` | 实例覆盖和主组件引用 |
| `get_variables` | — | 所有变量集合，模式和原始值 |
| `get_variable_tokens` | — | 按集合和模式分组的设计令牌 |
| `get_node_variable_bindings` | `nodeId` | 绑定到节点的变量及其解析的模式值 |
### 资产和图像导出
| 工具 | 关键参数 | 描述 |
|---|---|---|
| `get_exportable_nodes` | `nodeId` | 扫描子树以查找具有导出设置或图像填充的节点 — 使用此功能在导出前发现资产 |
| `get_screenshot` | `nodeId/nodeIds`, `format`, `scale`, `outputPath`, `outputDir` | 将节点导出为 PNG，JPG，PDF 或 SVG。返回 `downloadUrl` 每个光栅节点；SVG 返回内联。 |
| `get_svg` | `nodeId/nodeIds`, `outputPath`, `outputDir` | 将节点导出为内联 SVG 标记字符串 |
| `get_image` | `nodeId` | 从节点中提取原始图像填充字节。返回 `downloadUrl`。 |
| `export_section_assets` | `nodeId`, `format`, `scale`, `outputDir` | 批量导出部分中的每个可导出资产。返回每个资产的 `downloadUrl`，或直接写入文件，如果提供 `outputDir`。 |
| `get_colors` | — | 从填充和笔画中提取的所有唯一十六进制颜色 |
| `get_fonts` | — | 文档中使用的所有字体系列和样式 |
#### 资产下载模型
`get_screenshot`、`get_image` 和 `export_section_assets` 将导出的文件写入 MCP 服务器的临时目录（TTL：10 分钟），并返回一个 `downloadUrl`。代理使用单个命令检索文件：
```bash
curl -o assets/hero.png "http://localhost:3001/dl/<id>"
```
此模式在所有部署拓扑结构中统一工作 — 本地，Docker 和隧道远程。当 MCP 服务器被隧道时，请设置 `MCP_PUBLIC_URL` 为公共 URL，以便返回的链接可从代理的机器访问。
**或者**，如果 MCP 服务器和代理共享文件系统（本地开发或带有卷挂载的 Docker），请传递 `outputPath`（单个节点）或 `outputDir`（批量）以直接写入文件，无需中间下载。
### 文本和复制
| 工具 | 关键参数 | 描述 |
|---|---|---|
| `get_text_content` | `nodeId`, `page` | 提取所有文本。范围到子树使用 `nodeId`，或使用 `page` 使用页面。省略两者以转储整个文件。 |
| `find_text_nodes` | `keyword`, `regex` | 通过关键字或正则表达式搜索文本节点 |
| `find_placeholders` | — | 检测 lorem ipsum，`{{double braces}}`，`[square brackets]` 和 "your text here" 模式 |
| `detect_text_overflow` | `page` | 查找文本节点的内容溢出其剪辑容器 |
| `check_text_consistency` | `group_by`, `page` | 审核文本样式一致性；按页面，字体大小或字体系列分组结果 |
| `get_text_segments` | `nodeId`, `fields` | 每个段落的富文本数据：字体，大小，颜色，权重，超链接 |
| `get_typography_tokens` | — | 所有本地文本样式的完整字体属性 |
| `set_text_content` | `nodeId`, `text` | 替换文本内容。处理混合字体节点。 |
| `create_text` | `text`, `x`, `y`, `fontSize`, `parentId` | 创建新的文本节点 |
### 写操作
| 工具 | 关键参数 | 描述 |
|---|---|---|
| `set_text_content` | `nodeId`, `text` — or `updates[]` | 替换文本内容。提供明确的错误，如果目标节点不是 TEXT 节点，列出其中找到的任何文本子节点。 |
| `set_node_visibility` | `nodeIds`, `visible` | 显示或隐藏一组节点 |
| `set_solid_fill` | `nodeId`, `color`, `opacity` — or `updates[]` | 替换节点的填充为纯十六进制颜色 |
| `set_node_properties` | `nodeId`, `name`, `x`, `y`, `width`, `height`, `opacity` — or `updates[]` | 更新节点几何或名称 |
| `create_text` | `text`, `x`, `|text`, `y`, `fontSize`, `parentId` | 创建新的文本节点 |
`set_text_content`、`set_solid_fill` 和 `set_node_properties` 接受一个 `updates` 数组，用于批量编辑 — 调用一次更新多个节点，遇到节点失败后继续，并返回每个节点的错误消息 `{ results, succeeded, failed }`：
```json
{ "tool": "set_text_content", "arguments": { "updates": [
{ "nodeId": "2650:516", "text": "Sign up free" },
{ "nodeId": "2650:517", "text": "No credit card required" }
] } }
```
### 代码生成
| 工具 | 关键参数 | 描述 |
|---|---|---|
| `to_html` | `nodeId` | 将节点转换为带有内联 CSS 的 HTML |
| `to_html_page` | `page` | 将整个 Figma 页面转换为独立的 HTML 文档 |
| `export_json` | `nodeId` | 将节点导出为 Figma REST API JSON（v1 格式） |
<p align="right">(<a href="#readme-top">返回顶部</a>)</p>
## 贡献
欢迎提交 Bug 报告和功能请求 — [打开一个问题][issues-url]。对于代码更改：
```bash
npm install # root dev tooling (ESLint)
npm run lint # type-aware lint across all three services
npm run typecheck # tsc --noEmit for websocket + mcp-server
```
保持拉取请求范围限定在一个更改内，并在提交前确保 `lint` 和 `typecheck` 通过。
<p align="right">(<a href="#readme-top">返回顶部</a>)</p>
<!-- MARKDOWN LINKS & IMAGES -->
[build-shield]: https://img.shields.io/github/actions/workflow/status/alfianyusufabdullah/figma-proxy-mcp/docker-build-push.yml?branch=main&style=flat-square
[build-url]: https://github.com/alfianyusufabdullah/figma-proxy-mcp/actions/workflows/docker-build-push.yml
[node-shield]: https://img.shields.io/badge/node-%E2%89%A522-339933?style=flat-square&logo=node.js&logoColor=white
[node-url]: https://nodejs.org
[mcp-shield]: https://img.shields.io/badge/MCP-Streamable%20HTTP-blueviolet?style=flat-square
[mcp-url]: https://modelcontextprotocol.io
[figma-shield]: https://img.shields.io/badge/Figma-Desktop%20Plugin-F24E1E?style=flat-square&logo=figma&logoColor=white
[figma-url]: https://www.figma.com/plugin-docs/
[issues-url]: https://github.com/alfianyusufabdullah/figma-proxy-mcp/issues
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器