使用说明

Figma MCP Server

独立的 Figma MCP (Model Context Protocol) 服务器，将 Figma 自动化工具暴露为 MCP 服务。支持本地 stdio 模式和远程 HTTP 模式部署。

✨ 功能特性

🔌 双模式支持：stdio 模式（本地）和 HTTP 模式（远程）
🎨 Figma 集成：完整的 Figma API 集成
🖼️ 智能图片识别：自动识别可下载的图片节点
🐳 Docker 支持：容器化部署
🔐 多种认证方式：支持环境变量、配置文件、HTTP Headers
📦 简化数据：自动简化 Figma 节点数据
🚀 易于部署：提供多种部署方式

🚀 安装

前置要求

Node.js >= 16.0.0
npm 或 yarn
Figma API Access Token

安装步骤

# 克隆仓库
git clone https://github.com/zhaojian2626/figma-mcp-server.git
cd figma-mcp-server

# 安装依赖
npm install

⚙️ 配置

方式一：配置文件（推荐用于本地开发）

复制配置文件模板：

cp config.json.example config.json

编辑 config.json，填入您的 Figma API 凭证：

{
  "figma": {
    "accessToken": "your-figma-access-token",
    "fileKey": "your-figma-file-key"
  },
  "output": {
    "directory": "output"
  }
}

获取 Figma API 凭证：

accessToken: 访问 Figma Settings → Personal access tokens 创建
fileKey: 从 Figma 文件 URL 获取，例如 https://www.figma.com/file/XXXXX/文件名 中的 XXXXX

方式二：环境变量（推荐用于生产环境）

export FIGMA_ACCESS_TOKEN="your-figma-access-token"
export FIGMA_FILE_KEY="your-figma-file-key"
export PORT=3001  # HTTP 服务器端口（可选）

方式三：HTTP Headers（用于远程访问）

在 Cursor MCP 配置中使用 HTTP Headers 传递凭证（见下方配置说明）。

配置优先级

服务器按以下优先级读取凭证：

HTTP Headers (X-Figma-Access-Token, X-Figma-File-Key)
环境变量 (FIGMA_ACCESS_TOKEN, FIGMA_FILE_KEY)
配置文件 (config.json)

🚢 部署方式

方式一：stdio 模式（本地 Cursor 使用）

直接运行服务器，通过标准输入输出与 Cursor 通信：

node server.js

方式二：HTTP 模式（远程访问）

启动 HTTP 服务器，支持远程访问：

node server-http.js

服务器将在 http://localhost:3001 启动（可通过 PORT 环境变量修改）。

🔧 Cursor MCP 配置

配置方式一：stdio 模式（本地）

在 Cursor 的 MCP 配置文件中添加：

配置文件位置：

macOS: ~/Library/Application Support/Cursor/User/globalStorage/mcp.json
Windows: %APPDATA%\Cursor\User\globalStorage\mcp.json
Linux: ~/.config/Cursor/User/globalStorage/mcp.json

{
  "mcpServers": {
    "figma-server": {
      "command": "node",
      "args": [
        "/path/to/figma-mcp-server/server.js"
      ],
      "env": {
        "FIGMA_ACCESS_TOKEN": "your-figma-access-token",
        "FIGMA_FILE_KEY": "your-figma-file-key"
      }
    }
  }
}

配置方式二：HTTP URL 模式（远程或本地 HTTP）

使用 localhost（仅本机）

{
  "mcpServers": {
    "figma-server": {
      "url": "http://localhost:3001",
      "headers": {
        "X-Figma-Access-Token": "your-figma-access-token",
        "X-Figma-File-Key": "your-figma-file-key"
      }
    }
  }
}

使用本地 IP（局域网访问）

{
  "mcpServers": {
    "figma-server": {
      "url": "http://192.168.x.x:3001",
      "headers": {
        "X-Figma-Access-Token": "your-figma-access-token",
        "X-Figma-File-Key": "your-figma-file-key"
      }
    }
  }
}

使用远程服务器

{
  "mcpServers": {
    "figma-server": {
      "url": "http://your-server-ip:3001",
      "headers": {
        "X-Figma-Access-Token": "your-figma-access-token",
        "X-Figma-File-Key": "your-figma-file-key"
      }
    }
  }
}

注意：

如果服务器已配置环境变量或配置文件，可以省略 headers 中的凭证
修改配置后需要完全退出并重启 Cursor 才能生效

完整配置示例

{
  "_comment": "Figma MCP Server 配置",
  "mcpServers": {
    "figma-server": {
      "url": "http://localhost:3001",
      "headers": {
        "X-Figma-Access-Token": "figd_xxxxx",
        "X-Figma-File-Key": "xxxxx"
      }
    }
  }
}

🛠️ 可用的 MCP Tools

⭐ 推荐工作流（ViewTree IR）

面向高保真 UI 还原（Compose / 基准测试）：

figma_get_view_tree(figmaUrl)
    → figma_download_assets(fileUrl, assets[], outputDir)
    → figma_get_screenshot(nodeId, scale=2)

步骤	工具	说明
1	`figma_get_view_tree`	返回 ViewTree IR + `assets[]` 清单（含 format/reasons）
2	`figma_download_assets`	本地落盘，支持 `png/svg/android-vector`，返回 `downloaded/failed`
3	`figma_get_screenshot`	默认 `scale=2`（720×1560 类 benchmark 参考图）
调试	`figma_get_node_raw`	Figma REST 原始 JSON

Legacy 工具（兼容旧流程）：figma_download_and_simplify、figma_download_images

基准验收脚本

npm install
npm run verify:view-tree          # 离线 IR 单测
npm run benchmark compare -- --reference ref.png --actual actual.png
npm run benchmark screenshot -- --url "https://figma.com/design/...?node-id=1256-5595" --scale 2 --out output/ref.png

1. `figma_list_frames`

列出 Figma 文件中所有页面及顶层可还原节点（Frame / Component / Component Set / Instance）。

参数：

fileUrl (string, 必需)
includeTypes (array, 可选): 默认 ["FRAME","COMPONENT","COMPONENT_SET","INSTANCE"]

[
  {
    "pageId": "0:1",
    "pageName": "Page 1",
    "nodes": [
      { "id": "2370:65", "name": "Home", "type": "FRAME" },
      { "id": "2370:66", "name": "Button/Primary", "type": "COMPONENT" }
    ],
    "frames": [ /* legacy alias，仅 FRAME 类型 */ ]
  }
]

1b. `figma_get_view_tree` ⭐ 主入口

获取 ViewTree IR（平台无关中间表示）。

IR 关键字段：

kind: Stack | Text | Image | Vector | Shape
clipToBounds / overflow: { axis, likelyScroll } — 滚动容器语义
assetHint: { source, exportAs, format, reasons }
role / renderReason: controlIcon / background / progressTrack 等
styleHint.composeTypography: Material Typography 映射建议

参数：figmaUrl — 完整 Figma URL（含 node-id）

1c. `figma_download_assets`

按 IR 下载资源到本地。支持 png / jpg / svg / android-vector。

返回：{ downloaded: [...], failed: [...] }

1d. `figma_get_node_raw`

调试用：返回 Figma REST API 原始 JSON。

2. `figma_download_and_simplify` [Legacy]

从 Figma 获取指定节点（Page 或 Frame）的瘦身版 JSON，面向 Android Jetpack Compose 代码生成。不会下载图片，也不会返回截图——这两个能力由独立的工具按需调用。

参数：

nodeId (string, 必需): 完整的 Figma URL（如 https://www.figma.com/design/{fileKey}/...?node-id=4-419），工具会从中提取 fileKey 与 nodeId

返回结构：

{
  "tokens": {
    "colors":     { "primary/500": { "value": "0xFF1976D2", "collection": "Brand", "source": "variable", "variableId": "..." } },
    "typography": { "Body/Medium": { "value": { "fontSize": 14, "fontWeight": 500, "lineHeightPx": 20 }, "collection": "Style", "source": "style" } },
    "spacing":    { "md": { "value": 16, "collection": "Layout", "source": "variable" } },
    "radius":     { "md": { "value": 12, "collection": "Layout", "source": "variable" } }
  },
  "root": {
    "id": "123:45",
    "name": "BuyButton",
    "type": "FRAME",
    "absoluteBoundingBox": { "x": 0, "y": 0, "width": 120, "height": 44 },
    "layoutMode": "HORIZONTAL",
    "itemSpacing": 8,
    "paddingLeft": 16, "paddingRight": 16, "paddingTop": 12, "paddingBottom": 12,
    "primaryAxisAlignItems": "CENTER",
    "counterAxisAlignItems": "CENTER",
    "fills": [
      { "type": "SOLID", "color": "0xFF1976D2", "boundVariable": { "name": "primary/500", "collection": "Brand" } }
    ],
    "cornerRadius": 22,
    "composableHint": "BuyButton",
    "resourceHint": null,
    "isImageNode": false,
    "children": [ /* ... */ ]
  },
  "assets": [
    { "nodeId": "123:46", "name": "ic/arrow_right", "kind": "icon" }
  ],
  "metadata": {
    "apiOptimization": { "apiCalls": ["getNodeData", "getLocalVariables"], "apiCallCount": 2, "strategy": "direct: getNodeData(nodeId)" },
    "nameFieldRules": { "description": "...", "rules": [ "..." ] }
  }
}

关键点：

保留 Figma 原字段名（layoutMode / primaryAxisAlignItems / absoluteBoundingBox 等），没有任何 Compose-专属的重命名
颜色统一 0xAARRGGBB，可以直接 Color(0xFF...)
tokens 字典 + boundVariable：节点引用处带上 token 名和 collection，方便映射到 MaterialTheme
composableHint：从图层名推出来的 PascalCase，LLM 可以当作 Composable 函数名参考
resourceHint / isImageNode：资源型节点的类型标注，配合 figma_download_images 使用
60s LRU 缓存：同一 fileKey::nodeId 在 60 秒内会直接命中缓存

3. `figma_download_images` [Legacy]

获取指定节点对应的 Figma CDN 图片 URL（代理模式，不存盘）。由调用方直接从返回的 URL 下载。

参数：

fileUrl (string, 必需): Figma 文件 URL
nodeIds (array, 必需): 要拉取的图片节点 ID 列表（通常从 figma_download_and_simplify 的 assets 或 isImageNode: true 节点里挑出来）

返回：每个节点的 imageUrl、建议文件名、以及成功/失败状态

4. `figma_get_screenshot`

获取指定节点的预览图，默认 scale=2（benchmark 标准），以 base64 嵌入 MCP image content 返回。

参数：

nodeId (string, 必需): 完整 Figma URL（含 node-id）
scale (number, 可选): PNG 缩放倍率，默认 2

使用建议：按需调用。增量改字段 / 查 token 不需要预览；生成新的 Composable、做视觉还原度自查时才调。

5. `figma_list_json_files`

列出 output 目录中历史生成的 JSON 和图片文件。

参数：无

返回：JSON 文件列表和图片文件列表

📖 使用示例

基本使用流程（面向 Android Compose）

拿瘦身版 spec + tokens：
```
figma_download_and_simplify(nodeUrl) → { tokens, root, assets, metadata }
```
root 里保留了 Figma 原字段名（layoutMode / primaryAxisAlignItems / fills...），颜色都是 0xAARRGGBB，token 引用点有 boundVariable，直接可用于生成 MaterialTheme / Row / Column / Box。
按需拉视觉预览（生成新 Composable、做视觉还原度自查时）：
```
figma_get_screenshot(nodeUrl) → 1x PNG（base64）
```
按需拉图片资源：
```
figma_download_images(fileUrl, nodeIds) → [{ nodeId, imageUrl, fileName }]
```
nodeIds 从步骤 1 返回的 assets 清单里挑。拿到 imageUrl 后由调用方自己决定把文件放到 drawable/、mipmap/ 还是压成 WebP，MCP 不做这部分处理。

资源节点识别规则

以下节点会被标记为资源型节点（resourceHint 非空 + isImageNode: true），同时在顶层 assets 清单中出现：

规则	`resourceHint`
节点名称以 `exp_` 开头（整个节点作为一张图片）	`"export"`
节点名称以 `svg_` 开头（以 SVG 格式导出）	`"svg"`
节点名称以 `ic/` 或 `icon/` 开头（图标节点）	`"icon"`
包含可见的 IMAGE 填充	`"image"`

Tokens 使用建议

tokens.colors → 对应 MaterialTheme.colorScheme（primary/secondary/background...）或自定义 Color 常量
tokens.typography → 对应 MaterialTheme.typography 里的 TextStyle
tokens.spacing → 抽成 dp 常量或 LocalSpacing
tokens.radius → 抽成 RoundedCornerShape 常量

节点引用处的 boundVariable.name 和 tokens.*.* 里的 key 一致，可直接查表。

📚 部署指南

详细的部署指南请参考：

DEPLOYMENT.md - 完整的部署文档
DEPLOYMENT_SUMMARY.md - 部署修改总结
MCP_CONFIG_GUIDE.md - MCP 配置详细指南

快速部署检查清单

[ ] 安装 Node.js >= 16.0.0
[ ] 安装依赖：npm install
[ ] 配置 Figma 凭证（环境变量或配置文件）
[ ] 启动服务器（stdio 或 HTTP 模式）
[ ] 配置 Cursor MCP
[ ] 重启 Cursor
[ ] 测试连接

🧪 测试

测试 HTTP 服务器

# 健康检查
curl -X OPTIONS http://localhost:3001

# 测试初始化
curl -X POST http://localhost:3001 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'

# 测试工具列表
curl -X POST http://localhost:3001 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

测试查询页面

curl -X POST http://localhost:3001 \
  -H "Content-Type: application/json" \
  -H "X-Figma-Access-Token: your-token" \
  -H "X-Figma-File-Key: your-file-key" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"figma_list_frames","arguments":{}}}'

❓ 常见问题

Q: 如何获取 Figma Access Token？

访问 https://www.figma.com/settings
找到 "Personal access tokens" 部分
点击 "Create new token"
复制生成的 token

Q: 如何获取 Figma File Key？

打开 Figma 文件
从 URL 中获取：https://www.figma.com/file/XXXXX/文件名
XXXXX 就是 fileKey

Q: stdio 模式和 HTTP 模式有什么区别？

stdio 模式：通过标准输入输出通信，适合本地 Cursor 使用
HTTP 模式：通过 HTTP 请求通信，支持远程访问和多个客户端

Q: 配置后无法连接？

A: 检查以下几点：

服务器是否正在运行
端口是否正确
凭证是否正确配置
防火墙是否允许访问
是否已重启 Cursor

Q: 如何查看服务器日志？

直接运行：查看终端输出
Docker：docker logs figma-mcp-server
PM2：pm2 logs figma-mcp-server

Q: 支持多个 Figma 文件吗？

A: 当前版本每个服务器实例支持一个 fileKey。如需支持多个文件，可以：

运行多个服务器实例（不同端口）
在 Cursor 中配置多个 MCP 服务器

📝 开发

项目结构

figma-mcp-server/
├── server.js              # stdio 模式服务器（工具注册 + 路由）
├── server-http.js         # HTTP 模式服务器（MCP Streamable HTTP）
├── figma-api.js           # Figma REST API 客户端（含 getLocalVariables）
├── downloader.js          # 老的 simplifyNode（保留但未调用）+ sanitizeName
├── transformers/
│   ├── figmaSpec.js       # 节点树去噪 + Figma 原字段名 + 颜色 0xAARRGGBB
│   ├── tokens.js          # Variables/Styles → tokens 字典 + 注入 boundVariable
│   └── hints.js           # composableHint + resourceHint + 顶层 assets 清单
├── config.json.example    # 配置文件模板
├── Dockerfile             # Docker 镜像配置
├── docker-compose.yml     # Docker Compose 配置
├── deploy.sh              # 部署脚本
├── AGENTS.md              # 给 LLM agent 看的工具使用指引
└── README.md              # 本文档

可用脚本

npm start          # 启动 stdio 模式服务器
npm run start:http # 启动 HTTP 模式服务器
npm run dev        # 开发模式（HTTP）
npm run docker:build # 构建 Docker 镜像
npm run docker:run   # 运行 Docker Compose
npm run docker:stop  # 停止 Docker Compose

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

MIT License

🔗 相关文档

📞 支持

如有问题，请：

查看常见问题
查看相关文档
提交 Issue

注意：请妥善保管您的 Figma Access Token，不要将其提交到代码仓库。