figma-android-mcp

基于 npm figma-android-mcp 从零复刻并增强的 Figma → Android MCP 服务。原包只发布打包后的 dist、没有公开源码；本项目完整重写，代码与文档完全属于你，可自由魔改、发布。

为 Claude Code / Cursor / VS Code 等 AI 编码工具提供 Figma 设计数据接入：给一个 Figma 链接，AI 即可完成 设计数据读取 → 图片/字体资源下载 → 按项目约定生成 Compose / View 代码 的全流程。

• ⚡ 秒级获取设计数据，无需手动导出
• 🎯 dp/sp/em 自动换算、多密度图片、字体本地化，Compose / View 双输出
• 🔌 stdio + HTTP(StreamableHTTP)双传输，兼容主流 AI 客户端
• 🧩 4 个工具 + 技能系统，产出对齐真实 Android 项目约定

快速上手

前置要求：Node.js >= 20.20.0

npm install && npm run build
node dist/bin.js --stdio --figma-api-key=<你的 Figma Token>

AI 客户端配置(Claude Code 示例)

{
  "mcpServers": {
    "figma-android-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/dist/bin.js", "--stdio", "--figma-api-key=your-token"]
    }
  }
}

也可 npx -y figma-a(发布到 npm 后,bin 命令仍是 figma-android-mcp)。想用远程 HTTP 模式:去掉 --stdio,默认监听 127.0.0.1:3333(POST /mcp)。

CLI 直接抓取(无需客户端)

node dist/bin.js fetch "https://www.figma.com/design/<fileKey>/...?node-id=123-456"
node dist/bin.js fetch --file-key=<key> --node-id=123:456 --json

MCP 工具

| 工具 | 作用 | | --- | --- | | get_figma_node | 获取节点设计数据:布局(dp)、字体(sp/em)、颜色、组件、图片清单;SECTION 多状态分组、>5 帧清单模式 | | download_figma_images | 图片下载:支持直接传 Figma 链接自动识别图片节点(或显式 nodes),默认 4x 单次拉取 + 本地缩放 3x/2x,转 WebP,裁剪/去重/路径安全 | | download_figma_fonts | 从 Google Fonts 下载 TTF 到 res/font/(离线、无 GMS 依赖),生成 font-family XML | | get_skill | 读取技能约束(布局规则、还原流程等) |

get_figma_node

| 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | fileKey | string | 是 | Figma 文件 Key | | nodeId | string | 是 | 节点 ID,如 1234:5678 | | depth | number | 否 | 遍历深度 | | includePreview | boolean | 否 | 附带渲染截图(PNG base64) | | manifestOnly | boolean | 否 | SECTION 立即返回清单模式 | | outputPlatform | enum | 否 | compose / views |

输出要点(YAML 默认 / JSON):

name: identidad-landing
type: FRAME
id: 338:1212
source: { fileKey, nodeId, name, url }   # Figma 出处,供代码注释引用
screen: { width: 360dp, height: 858dp, windowSizeClass: compact }
nodes: [ ... ]                            # 布局/文本/样式,含 isInput / isButton / aspectRatio
styles: { var_XXX: {...} }                # 去重后的样式表
components: { id: {name, key, propertyDefinitions} }   # COMPONENT 定义
componentSets: { ... }                    # COMPONENT_SET 定义
imageAssets: [ ... ]                      # nodeId/fileName/category + imageRef/cropTransform
systemUi: { excluded: 1, note }           # 状态栏已剔除,提示用 WindowInsets
_REQUIRED_RULES: [ ... ]                  # 生成代码前必读的技能

• 布局字段风格由 outputPlatform 控制:compose(Column(width=…, arrangement=…))/ views(orientation/gravity/layout_width)
• INSTANCE 节点带 componentId + componentName(已解析组件名)+ componentProperties,AI 直接复用组件
• 同名图片自动去重(vector.png / vector_2.png …);带 transform 的填充带 cropTransform

download_figma_images

| 参数 | 默认值 | 说明 | | --- | --- | --- | | url | — | Figma 设计稿链接,替代 fileKey/nodeId;省略 nodes 时自动扫描识别图片节点 | | nodes | — | 显式指定(可省略,省略则自动识别);每项 nodeId+fileName+category,可带 imageRef/gifRef/cropTransform/needsCropping/requiresImageDimensions/filenameSuffix | | localPath | — | 如 app/src/main/res(相对 --image-dir,路径安全检查) | | densities | ["xxxhdpi","xxhdpi","xhdpi"] | 4x/3x/2x;只向 Figma 请求 1 次最高倍(4x),其余本地缩放 | | format | webp | webp(默认,本地转码)/ png;动图恒为 .gif | | targetWidth | — | xxxhdpi 目标宽度(px),图标建议 192(=48dp×4);按 1/4、1.5/4、2/4、3/4、1 比例生成各桶(与 figma-image skill 一致) | | onlyExportTagged | true | 仅下载设计师标记导出的节点 |

• 缩放比 = 桶倍数 ÷ 4;渲染节点走缩放,图片填充/GIF/SVG 原样复制
• targetWidth 图标模式:固定 xxxhdpi 宽度(如 192px),五档密度按 1/4…1 等比生成 —— 与 figma-image skill 的 --target-width 行为一致
• 跨桶 sha256 去重 + Alias Map;失败桶记入 Density Fallbacks

download_figma_fonts

| 参数 | 默认值 | 说明 | | --- | --- | --- | | families | — | 显式家族;省略则用 fileKey(+nodeId)扫描设计稿自动收集 | | weights | 设计用到的字重 / [400] | 只下载这些字重 | | localPath | app/src/main/res/font | 保存目录(相对 imageDir) |

• 走 Google Fonts 公开 CSS2 API(无需 key),legacy UA 取完整 TTF(CJK 无子集拆分)
• 按 Android 命名落盘:poppins_regular.ttf / poppins_bold.ttf(字重名),并自动生成 res/font/poppins.xml(font-family 资源),Compose 里 FontFamily(R.font.poppins) 直接引用 —— 与真实项目字体资源约定一致
• 不在 Google Fonts 的家族(如 PingFang SC)明确报告,走系统回退或向设计师索取

get_skill

name 可选;不传列出所有技能。内置技能:

| 技能 | 内容 | | --- | --- | | android-layout | 强制布局约束:宽度响应式、600dp 内自适应(BoxWithConstraints)、控件复用、Edge-to-Edge、IME、图片不变形(aspectRatio)、按钮多行、字体实现、Figma 出处注释、对齐项目已有约定、纯色占位、反模式检测 | | figma-android-mcp-skill | Figma → Android 还原流程:解析 → 获取 → 下载 → 生成 | | figma-image | Figma → Android 密度 WebP(mipmap):走 download_figma_images 的 url 自动识别 + targetWidth 图标模式,MCP 原生实现,无需脚本 |

自定义技能:在 --skills-dir 下放带 YAML frontmatter 的 Markdown(name/title/description 必填),同名覆盖内置。示例见 skills/compose-style.md。

配置

三层优先级:CLI 参数 > 环境变量 > 默认值;.env 自动加载(参考 .env.example)。

| CLI 参数 | 环境变量 | 默认值 | 说明 | | --- | --- | --- | --- | | --figma-api-key / --figma-oauth-token | FIGMA_API_KEY / FIGMA_OAUTH_TOKEN | — | 认证(必填其一) | | --stdio | — | 关闭 | stdio 模式 | | --port / --host | FRAMELINK_PORT/PORT、FRAMELINK_HOST | 3333 / 127.0.0.1 | HTTP 模式 | | --output-platform | OUTPUT_PLATFORM | compose | compose / views | | --design-density | FRAMELINK_DESIGN_DENSITY | auto | px→dp 除数(auto 按画布宽推断) | | --image-dir | IMAGE_DIR | cwd | 图片/字体保存根目录 | | --skills-dir | SKILLS_DIR | — | 自定义技能目录 | | --json | OUTPUT_FORMAT=json | YAML | JSON 输出 | | --proxy | FIGMA_PROXY | — | 代理;none 忽略环境代理 | | --no-telemetry | FRAMELINK_TELEMETRY=off/DO_NOT_TRACK=1 | — | 兼容原版(本构建不收集遥测) | | --skip-image-downloads | SKIP_IMAGE_DOWNLOADS=true | 关闭 | 不注册图片下载工具 |

测试/代理可用 FIGMA_API_BASE_URL、GOOGLE_FONTS_CSS_API 覆盖 API 地址。

开发

npm run build        # tsup 构建 → dist/
npm run type-check   # tsc --noEmit
npm test             # vitest(单测 + mock Figma/Google Fonts 端到端,无需真实 token)
npm run start -- --stdio --figma-api-key=<token>
node scripts/smoke-stdio.mjs   # stdio 冒烟:4 工具 + 校验错误

测试覆盖:URL 解析 / 单位换算 / 密度映射 / 布局序列化 / 配置优先级 / 技能 frontmatter / 技能内容完整性守护 / 全链路 mock(拉取→简化→图片→字体→路径安全)。

目录结构

src/
├── bin.ts               # CLI(cleye):server + fetch 子命令
├── server.ts            # MCP 装配:createServer / stdio / HTTP(StreamableHTTP)
├── config.ts            # CLI > env > 默认值 解析
├── cli-fetch.ts         # fetch 子命令
├── figma/               # HTTP 工具 / FigmaService / 图片下载编排 / WebP 编解码
├── fonts/               # Google Fonts 客户端(TTF + font-family XML)
├── simplify/            # 简化引擎:walker / extractors / 布局 / 密度 / 类型
├── tools/               # 4 个工具的 schema + 实现
├── skills/              # 内置技能 + frontmatter 加载器
├── progress.ts          # MCP 进度通知
├── telemetry.ts         # 遥测桩(不收集)
└── index.ts             # 公开 API
test/                    # vitest 单测 + e2e(mock 服务器)
skills/                  # 自定义技能示例
scripts/                 # stdio 冒烟脚本

与原版的差异

| 项 | 原版 | 本实现 | | --- | --- | --- | | 源码 | 仅打包 dist | 完整 TS 源码,分层清晰 | | 多密度下载 | 每桶各调一次 Figma | 单次 4x 下载 + 本地缩放,API 调用 N→1 | | 图片格式 | 恒 PNG | 默认 WebP(libwebp WASM,离线) | | 字体 | 不处理 | download_figma_fonts:Google Fonts TTF 本地化 + font-family XML | | 组件/状态栏 | 部分 | 组件定义输出 + INSTANCE 解析 + 状态栏过滤 + isInput/isButton + source 出处 | | 技能 | 布局约束 | 十余项强制规则(响应式/复用/Edge-to-Edge/IME/图片/按钮/字体/出处/对齐项目) | | 遥测 | PostHog 默认开 | 不收集,保留兼容 flag | | 简化引擎 | 深度启发式 | 核心等价(overlay/实例 override/300KB 预算等未复刻,见待办) |

待办(已知缺口)

• [ ] 429/5xx 请求自动重试(is_retryable 已标记未消费)
• [ ] format=svg → VectorDrawable 导出
• [ ] 无障碍 contentDescription / 深色模式 / RTL 技能规则
• [ ] overlay 检测(toast/dialog 瞬态 UI)
• [ ] 实例 override 差异输出
• [ ] Figma variables(设计 token)解析
• [ ] HTTP 模式 / progress 自动化测试

License

MIT