Figma-Context-MCP-AIR

Figma Context MCP AIR

让你的 AI 编码 Agent 访问 Figma 设计数据。
以像素级精度在任意框架中实现设计，一次搞定。

---

这是什么？

figma-context-mcp-air 是一个 Model Context Protocol (MCP) 服务，可让 AI 编码工具（Cursor、Claude、Windsurf 等）直接访问你的 Figma 设计数据。

它提供 9 个工具，涵盖从设计到代码的完整工作流：

工具	描述
get_figma_data	完整设计数据——布局、文本、视觉元素、组件（YAML/JSON）
get_design_context	get_figma_data 的别名，命名与官方 Figma MCP 工具一致
download_figma_images	将 Figma 节点的 PNG/SVG 资源下载到本地文件系统
get_screenshot	将 Figma 节点截取为 base64 PNG，供 AI 进行视觉检查
get_metadata	精简的 XML 图层层级结构，便于在完整提取前快速查找节点
get_variable_defs	所有设计令牌——颜色、排版、间距、效果和样式
whoami	验证你的 Figma 身份验证状态并查看套餐等级
create_design_system_rules	为你的项目生成特定框架的设计系统文档
get_figjam	将 FigJam 画板内容（便笺、连接线、形状）提取为 XML

在将数据返回给 AI 之前，服务会简化并筛选原始 Figma API 响应，只保留代码生成所需的布局和样式信息。这能减少干扰，大幅提高 AI 的准确性。

---

开始使用

使用此服务需要 Figma Personal Access Token。
如何创建 Figma API 访问令牌 →

MacOS / Linux

将以下内容添加到 MCP 客户端配置文件中（例如 ~/.cursor/mcp.json、claude_desktop_config.json）：

{
  "mcpServers": {
    "Figma MCP AIR": {
      "command": "npx",
      "args": ["-y", "figma-context-mcp-air", "--figma-api-key=YOUR-KEY", "--stdio"]
    }
  }
}

Windows

{
  "mcpServers": {
    "Figma MCP AIR": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "figma-context-mcp-air", "--figma-api-key=YOUR-KEY", "--stdio"]
    }
  }
}

使用环境变量

你也可以在 env 字段中设置 FIGMA_API_KEY，而不是将其作为标志传入：

{
  "mcpServers": {
    "Figma MCP AIR": {
      "command": "npx",
      "args": ["-y", "figma-context-mcp-air", "--stdio"],
      "env": {
        "FIGMA_API_KEY": "YOUR-KEY"
      }
    }
  }
}

---

工作原理

1. 打开 AI 编码工具的聊天界面（例如 Cursor 中的 Agent 模式）。
2. 粘贴 Figma 文件、画框或组件的链接。
3. 让 AI 实现该设计。
4. AI 调用 get_design_context（或 get_figma_data）获取结构化设计数据，然后编写代码。

对于更高级的工作流，AI 可以：

• 调用 get_screenshot，在实现前直观检查节点
• 调用 get_variable_defs，提取设计令牌并映射为 CSS 变量
• 调用 get_metadata，在获取完整数据前快速查看图层概览
• 调用 create_design_system_rules，生成针对项目的编码指南

---

配置选项

CLI 标志	环境变量	默认值	描述
--figma-api-key	FIGMA_API_KEY	(必需)	你的 Figma Personal Access Token
--figma-oauth-token	FIGMA_OAUTH_TOKEN	—	OAuth Bearer 令牌（PAT 的替代方式）
--port	PORT	3333	HTTP 服务端口（仅限 HTTP 模式）
--json	OUTPUT_FORMAT=json	YAML	返回 JSON 而不是 YAML
--skip-image-downloads	SKIP_IMAGE_DOWNLOADS	false	禁用 download_figma_images 工具
--image-dir	—	—	下载图像的自定义目录
--stdio	NODE_ENV=cli	—	以 stdio 模式运行（MCP 客户端必需）

---

工具参考

get_figma_data / get_design_context

获取并简化 Figma 文件或特定节点的设计数据。以 YAML 或 JSON 格式返回布局（flexbox/grid）、排版、颜色、边框、效果和组件元数据。

参数：

• fileKey (必填) — Figma URL 中的键：figma.com/design/<fileKey>/...
• nodeId (可选) — URL 中的节点 ID：?node-id=<nodeId>。使用 1234:5678 格式。
• depth (可选) — 遍历深度。仅在明确需要时使用。

---

download_figma_images

将 Figma 节点的 PNG 或 SVG 渲染图下载到本地文件系统。

参数：

• fileKey (必填)
• nodes (必填) — { nodeId, fileName } 对象数组
• localPath (必填) — 保存图像的目录
• pngScale (可选) — PNG 导出的缩放比例（默认值：1）
• svgOptions (可选) — SVG 导出选项（轮廓化文本、包含 ID、简化描边）

---

get_screenshot

将 Figma 节点截取为 2x PNG 并保存到磁盘。适用于视觉验证。

参数：

• fileKey (必填)
• nodeId (必填)
• localPath (可选) — 保存目录（默认值：./screenshots）
• fileName (可选) — 不含扩展名的输出文件名

---

get_metadata

返回节点层级的稀疏 XML 表示（depth=2）。在获取完整设计上下文前，可用它快速发现图层。

参数：

• fileKey (必填)
• nodeId (必填)

---

get_variable_defs

获取 Figma 文件中的所有设计令牌——变量集合（颜色、间距、排版）和已发布样式（效果、文本样式、填充样式）。返回采用 CSS 自定义属性语法的数据。

参数：

• fileKey (必填)

---

whoami

返回已认证用户的 Figma 账户信息（姓名、电子邮件、套餐等级）。可用于验证 API 密钥是否有效。

参数： 无

---

create_design_system_rules

生成全面的 Markdown 模板，其中包含针对项目的设计系统规则。根据语言与框架的组合进行定制。将输出保存到 CLAUDE.md 或项目的 AI 指令文件中。

参数：

• clientLanguages (必填) — 例如 "typescript,javascript"
• clientFrameworks (必填) — "react"、"vue"、"svelte"、"angular" 或 "unknown"

---

get_figjam

将 FigJam 白板中的内容——便签、连接线、形状、分区——提取为带有截图 URL 的 XML。

参数：

• fileKey (必填)
• nodeId (可选) — FigJam 白板中的特定分区或画板

---

开发

# Install dependencies
pnpm install

# Build
pnpm build

# Development mode (HTTP, with watch)
pnpm dev

# Development mode (stdio)
pnpm dev:cli

# Run tests
pnpm test

# Type check
pnpm type-check

# Lint
pnpm lint

---

贡献

欢迎贡献！提交拉取请求前，请阅读 CONTRIBUTING.md。

对于重大功能，请先创建议题，讨论实施方案。

---

许可证

MIT — 请参阅 LICENSE

---

致谢

本项目是 GLips/Figma-Context-MCP（Framelink MCP 服务）的分支，并扩展了其他工具，以匹配 Figma 官方 MCP 工具的完整功能范围。