Figma MCP Server

<h1 align="center"> <br> <img src="https://upload.wikimedia.org/wikipedia/commons/3/33/Figma-logo.svg" alt="Figma MCP" width="80"> <br> Figma Context MCP <br> </h1> <p align="center"> <strong>用于 AI 编码工具与 Figma 设计无缝集成的 MCP 服务器</strong> </p> <p align="center"> <a href="https://smithery.ai/server/@1yhy/Figma-Context-MCP"> <img src="https://smithery.ai/badge/@1yhy/Figma-Context-MCP" alt="Smithery Badge"> </a> <a href="https://www.npmjs.com/package/@yhy2001/figma-mcp-server"> <img src="https://img.shields.io/npm/v/@yhy2001/figma-mcp-server" alt="npm version"> </a> <a href="https://github.com/1yhy/Figma-Context-MCP/blob/main/LICENSE"> <img src="https://img.shields.io/github/license/1yhy/Figma-Context-MCP" alt="License"> </a> <a href="https://github.com/1yhy/Figma-Context-MCP/stargazers"> <img src="https://img.shields.io/github/stars/1yhy/Figma-Context-MCP" alt="Stars"> </a> <img src="https://img.shields.io/badge/TypeScript-5.7-blue?logo=typescript" alt="TypeScript"> <img src="https://img.shields.io/badge/MCP-1.24-green" alt="MCP SDK"> </p> <p align="center"> <a href="#功能特性">功能特性</a> • <a href="#快速开始">快速开始</a> • <a href="#mcp-能力">MCP 能力</a> • <a href="#架构">架构</a> • <a href="#文档">文档</a> • <a href="./README.md">English</a> </p> --- ## 这是什么？ Figma Context MCP 是一个 [模型上下文协议 (MCP)](https://modelcontextprotocol.io/) 服务器，用于连接 Figma 设计与 AI 编码助手，如 [Cursor](https://cursor.sh/)、[Windsurf](https://codeium.com/windsurf) 和 [Cline](https://cline.bot/)。 当 AI 工具能够直接访问 Figma 设计数据时，它们能够一次性生成更准确的代码——效果远超使用截图。 > **说明**：本项目基于 [Figma-Context-MCP](https://github.com/GLips/Figma-Context-MCP) 改进，优化了数据结构和智能布局检测算法。 ## 功能特性 ### 核心能力 | 能力 | 描述 | | -------------------- | ------------------------------------------ | | **智能布局检测** | 从绝对定位自动推断 Flexbox/Grid 布局 | | **图标合并** | 智能合并矢量图层为单个可导出图标 | | **CSS 生成** | 将 Figma 样式转换为干净可用的 CSS | | **图片导出** | 下载带有正确命名的图片和图标 | | **多层缓存** | L1 内存 + L2 磁盘缓存，减少 API 调用 | | **设计转代码提示词** | 内置专业提示词模板，指导 AI 生成高质量代码 | | **轻量资源访问** | Resources API 提供低 Token 消耗的数据访问 | ### 核心改进 | 功能 | 改进前 | 改进后 | | -------- | ------------ | ---------------------- | | 图标导出 | ~45 个碎片 | 2 个合并（减少 96%） | | 布局检测 | 手动绝对定位 | 自动 Flexbox/Grid 推断 | | CSS 输出 | 原始值 | 优化后移除默认值 | | API 调用 | 每次请求 | 24 小时智能缓存 | ## 快速开始 ### 前提条件 - Node.js >= 18.0.0 - 具有 API 访问权限的 Figma 账户 ### 安装 **通过 Smithery（推荐）** ```bash npx -y @smithery/cli install @1yhy/Figma-Context-MCP --client claude ``` **通过 npm** ```bash npm install -g @yhy2001/figma-mcp-server ``` **从源码安装** ```bash git clone https://github.com/1yhy/Figma-Context-MCP.git cd Figma-Context-MCP pnpm install pnpm build ``` ### 配置 #### 1. 获取 Figma API 令牌 1. 访问 [Figma 账户设置](https://www.figma.com/settings) 2. 滚动到 "Personal access tokens" 3. 点击 "Create new token" 4. 复制令牌 #### 2. 配置 AI 工具 <details> <summary><strong>Cursor / Windsurf / Cline</strong></summary> 添加到 MCP 配置文件： ```json { "mcpServers": { "Figma": { "command": "npx", "args": ["-y", "@yhy2001/figma-mcp-server", "--stdio"], "env": { "FIGMA_API_KEY": "your-figma-api-key" } } } } ``` </details> <details> <summary><strong>HTTP/SSE 模式（本地开发）</strong></summary> ```bash # 启动服务器 figma-mcp --figma-api-key=<your-key> --port=3333 # 通过 SSE 连接 # URL: http://localhost:3333/sse ``` </details> ### 使用示例 ``` 请实现这个 Figma 设计：https://www.figma.com/design/abc123/MyDesign?node-id=1:234 使用 React 和 Tailwind CSS。 ``` --- ## MCP 能力 本服务器提供完整的 MCP 能力支持： ``` ┌─────────────────────────────────────────────────────────────┐ │ Figma MCP Server v1.0.2 │ ├─────────────────────────────────────────────────────────────┤ │ Tools (2) AI 调用的操作 │ │ ├── get_figma_data 获取设计数据 │ │ └── download_figma_images 下载图片资产 │ ├─────────────────────────────────────────────────────────────┤ │ Prompts (3) 用户选择的提示词模板 │ │ ├── design_to_code 设计转代码完整流程 │ │ ├── analyze_components 组件结构分析 │ │ └── extract_styles 样式 Token 提取 │ ├─────────────────────────────────────────────────────────────┤ │ Resources (5) 轻量级数据资源 │ │ ├── figma://help 使用指南 │ │ ├── figma://file/{key} 文件元数据 (~200 tokens) │ │ ├── figma://file/{key}/styles 设计 Tokens (~500 tokens) │ │ ├── figma://file/{key}/components 组件列表 (~300 tokens) │ │ └── figma://file/{key}/assets 资产清单 (~400 tokens) │ └─────────────────────────────────────────────────────────────┘ ``` ### Tools（工具） | 工具 | 描述 | 参数 | | ----------------------- | ------------------ | --------------------------------- | | `get_figma_data` | 获取简化的设计数据 | `fileKey`, `nodeId?`, `depth?` | | `download_figma_images` | 下载图片和图标 | `fileKey`, `nodes[]`, `localPath` | ### Prompts（提示词） 内置的专业提示词模板，帮助 AI 生成高质量代码： | 提示词 | 描述 | 参数 | | -------------------- | ---------------------- | ---------------------------------- | | `design_to_code` | 完整的设计转代码工作流 | `framework?`, `includeResponsive?` | | `analyze_components` | 分析组件结构和复用性 | - | | `extract_styles` | 提取设计 Tokens | - | **design_to_code 工作流包含：** 1. **项目分析** - 读取主题配置、全局样式、组件库 2. **结构分析** - 识别页面模式、组件拆分策略 3. **ASCII 布局图** - 生成带组件和资产标注的布局蓝图 4. **资产管理** - 分析、下载和组织图片/图标 5. **代码生成** - 遵循项目规范生成代码 6. **无障碍优化** - 语义化 HTML、ARIA 标签 7. **响应式适配** - 移动端布局调整 ### Resources（资源） 轻量级数据访问，节省 Token 消耗： ```bash # 获取文件元数据（~200 tokens） figma://file/abc123 # 获取设计 Tokens（~500 tokens） figma://file/abc123/styles # 获取组件列表（~300 tokens） figma://file/abc123/components # 获取资产清单（~400 tokens） figma://file/abc123/assets ``` **Resources vs Tools 对比：** | 特性 | Tools | Resources | | ---------- | ---------------- | ------------------- | | 控制方 | AI 自动调用 | 用户/客户端主动读取 | | Token 消耗 | 较高（完整数据） | 较低（精简摘要） | | 用途 | 执行操作 | 浏览和探索 | --- ## 架构 ``` ┌──────────────────────────────────────────────────────────────┐ │ MCP Server │ ├──────────────────────────────────────────────────────────────┤ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │ │ │ Tools │ │ Prompts │ │ Resources │ │ │ │ (2 个工具) │ │ (3 个模板) │ │ (5 个资源) │ │ │ └──────┬──────┘ └─────────────┘ └──────────┬──────────┘ │ │ │ │ │ │ └──────────────────┬───────────────────┘ │ │ ▼ │ │ ┌────────────────────────────────────────────────────────┐ │ │ │ FigmaService │ │ │ │ API 调用 • 验证 • 错误处理 • 限流 │ │ │ └────────────────────────┬───────────────────────────────┘ │ │ │ │ │ ┌─────────────────┴─────────────────┐ │ │ ▼ ▼ │ │ ┌─────────────────┐ ┌─────────────────────┐ │ │ │ CacheManager │ │ Parser + Algo │ │ │ │ L1: LRU 内存 │ │ • 布局检测 │ │ │ │ L2: 磁盘持久化 │ │ • 图标合并 │ │ │ └─────────────────┘ │ • CSS 生成 │ │ │ └─────────────────────┘ │ └──────────────────────────────────────────────────────────────┘ ``` ### 缓存系统 两层缓存架构，显著减少 API 调用： | 层级 | 存储 | 容量 | TTL | 用途 | | ---- | -------- | ------------------ | --------- | -------------- | | L1 | 内存 LRU | 100 节点 / 50 图片 | 5-10 分钟 | 热数据快速访问 | | L2 | 磁盘 | 500MB | 24 小时 | 持久化缓存 | ### 布局检测算法 自动将绝对定位转换为语义化的 Flexbox/Grid 布局： ``` 输入（Figma 绝对定位）: ┌─────────────────────────┐ │ ■ (10,10) ■ (110,10) │ │ ■ (10,60) ■ (110,60) │ └─────────────────────────┘ 输出（推断的 Grid）: display: grid grid-template-columns: 100px 100px grid-template-rows: 50px 50px gap: 10px ``` --- ## 项目结构 ``` src/ ├── algorithms/ # 智能算法 │ ├── layout/ # 布局检测（Flex/Grid 推断） │ └── icon/ # 图标合并检测 ├── core/ # 核心解析 │ ├── parser.ts # Figma 数据解析 │ ├── style.ts # CSS 样式生成 │ ├── layout.ts # 布局处理 │ └── effects.ts # 效果处理 ├── services/ # 服务层 │ ├── figma.ts # Figma API 客户端 │ └── cache/ # 多层缓存系统 ├── prompts/ # MCP 提示词模板 ├── resources/ # MCP 资源处理器 ├── types/ # TypeScript 类型定义 ├── utils/ # 工具函数 ├── server.ts # MCP 服务器主入口 └── index.ts # CLI 入口 tests/ ├── fixtures/ # 测试数据 │ ├── figma-data/ # Figma API 返回的原始 JSON │ └── expected/ # 预期输出快照 ├── integration/ # 集成测试 │ ├── layout-optimization.test.ts # 布局优化测试 │ ├── output-quality.test.ts # 输出质量验证 │ └── parser.test.ts # 解析器测试 └── unit/ # 单元测试 ├── algorithms/ # 算法测试（布局检测、图标合并） ├── resources/ # 资源处理器测试 └── services/ # 服务层测试 scripts/ └── fetch-test-data.ts # 获取 Figma 测试数据工具 ``` --- ## 文档 ### 核心算法 | 中文 | English | | -------------------------------------------------- | ----------------------------------------------------- | | [布局检测算法](./docs/zh-CN/layout-detection.md) | [Layout Detection](./docs/en/layout-detection.md) | | [图标检测算法](./docs/zh-CN/icon-detection.md) | [Icon Detection](./docs/en/icon-detection.md) | | [缓存架构设计](./docs/zh-CN/cache-architecture.md) | [Cache Architecture](./docs/en/cache-architecture.md) | ### 研究文档 | 中文 | English | | --------------------------------------------------------- | ------------------------------------------------------------------- | | [Grid 布局研究](./docs/zh-CN/grid-layout-research.md) | [Grid Layout Research](./docs/en/grid-layout-research.md) | | [布局检测研究](./docs/zh-CN/layout-detection-research.md) | [Layout Detection Research](./docs/en/layout-detection-research.md) | ### 架构文档 | 中文 | English | | ---------------------------------------- | ----------------------------------------- | | [系统架构](./docs/zh-CN/architecture.md) | [Architecture](./docs/en/architecture.md) | --- ## 命令行选项 | 选项 | 描述 | 默认值 | | ----------------- | --------------------- | ------ | | `--figma-api-key` | Figma API 令牌 | 必需 | | `--port` | HTTP 模式的服务器端口 | 3333 | | `--stdio` | 以 stdio 模式运行 | false | | `--help` | 显示帮助 | - | --- ## 贡献指南 欢迎贡献！ ```bash # 设置 git clone https://github.com/1yhy/Figma-Context-MCP.git cd Figma-Context-MCP pnpm install # 开发 pnpm dev # 监听模式 pnpm test # 运行测试（272 个测试用例） pnpm lint # 代码检查 pnpm build # 构建 # 调试 pnpm inspect # MCP Inspector # 使用自己的 Figma 数据测试 pnpm tsx scripts/fetch-test-data.ts <fileKey> <nodeId> <outputName> # 提交（使用约定式提交） git commit -m "feat: 添加新功能" ``` ### 提交类型 | 类型 | 描述 | | ---------- | -------- | | `feat` | 新功能 | | `fix` | Bug 修复 | | `docs` | 文档更新 | | `style` | 代码风格 | | `refactor` | 代码重构 | | `test` | 测试相关 | | `chore` | 其他维护 | ### 使用自己的 Figma 数据测试 你可以使用自己的 Figma 设计来测试布局检测和优化效果： #### 1. 配置环境变量 ```bash # 复制环境变量模板 cp .env.example .env # 编辑 .env 文件，填入你的配置 FIGMA_API_KEY=your_figma_api_key_here TEST_FIGMA_FILE_KEY=your_file_key # 可选 TEST_FIGMA_NODE_ID=your_node_id # 可选 ``` #### 2. 获取 Figma 节点数据 ```bash # 方式一：使用命令行参数（推荐） pnpm tsx scripts/fetch-test-data.ts <fileKey> <nodeId> <outputName> # 示例：获取指定节点 pnpm tsx scripts/fetch-test-data.ts UgtwrncR3GokKDIS7dpm4Z 402-34955 my-design # 方式二：使用环境变量 TEST_FIGMA_FILE_KEY=xxx TEST_FIGMA_NODE_ID=123-456 pnpm tsx scripts/fetch-test-data.ts ``` **参数说明：** | 参数 | 说明 | 获取方式 | | ------------ | -------------- | ------------------------------------------------------- | | `fileKey` | Figma 文件标识 | URL 中 `/design/` 后的部分，如 `UgtwrncR3GokKDIS7dpm4Z` | | `nodeId` | 节点 ID | URL 中 `node-id=` 参数，如 `402-34955` | | `outputName` | 输出文件名 | 自定义，如 `my-design` | **示例 URL 解析：** ``` https://www.figma.com/design/UgtwrncR3GokKDIS7dpm4Z/MyProject?node-id=402-34955 ↑ fileKey ↑ nodeId ``` #### 3. 运行测试验证输出 ```bash # 运行所有测试 pnpm test # 只运行集成测试（验证布局优化效果） pnpm test tests/integration/ # 查看输出的 JSON 文件 ls tests/fixtures/figma-data/ ``` #### 4. 分析优化结果 测试会自动验证： - **数据压缩率** - 通常 >50% 压缩 - **布局检测** - Flex/Grid 布局识别率 - **CSS 属性** - 冗余属性清理 - **输出质量** - 结构一致性检查 如果测试失败，说明输出可能不符合预期，可以根据错误信息调整或报告 issue。 --- ## 许可证 [MIT](./LICENSE) © 1yhy ## 致谢 - [Figma-Context-MCP](https://github.com/GLips/Figma-Context-MCP) - 原始项目 - [Model Context Protocol](https://modelcontextprotocol.io/) - MCP 规范 - [Best-README-Template](https://github.com/othneildrew/Best-README-Template) - README 模板参考 --- <p align="center"> 为 AI 编码社区用 ❤️ 制作 </p>