MCP Figma Demo

MCP-Figma 演示

从Figma导出支持缓存的PNG图像。这是一个命令行工具（第一阶段），计划增加对MCP服务器的支持以集成AI功能（第二阶段）。

特点/特性

• 🖼️ 从Figma导出高分辨率PNG图片
• 💾 智能缓存以避免达到速率限制
• 📊 可选的元数据导出（JSON）
• ⚡ 处理速率限制并自动重试
• 🔐 通过环境变量实现安全的令牌管理

先决条件

• Node.js >= 22.0.0（译为中文即：Node.js 版本大于等于 22.0.0）
• pnpm（推荐）或 npm
• Figma 个人访问令牌

安装

# Clone the repository
git clone 
cd mcp-figma-demo

# Install dependencies
pnpm install

# Set up Git hooks (for development)
pnpm simple-git-hooks

# Build the project
pnpm build

配置

Figma代币

将您的 Figma 个人访问令牌设置为环境变量：

export FIGMA_PERSONAL_TOKEN="your-token-here"

或者通过它传递 --token 选项（出于安全原因，不建议使用）。

获取您的Figma个人访问令牌

1. 首选 Figma 账户设置
2. 滚动到“个人访问令牌”
3. 点击“创建新的个人访问令牌”
4. 给它起个名字，然后点击“创建”
5. 复制令牌（之后将无法再次查看！）

使用方法

基本用法

# Export a single node
mcp-figma-demo "https://www.figma.com/file/ABC123/..." --nodes "1:2"

# Export multiple nodes
mcp-figma-demo "https://www.figma.com/file/ABC123/..." --nodes "1:2,1:3,1:4"

# Export with metadata
mcp-figma-demo "https://www.figma.com/file/ABC123/..." --nodes "1:2" --with-metadata

选项

-o, --output          Output directory (default: ./output)
-t, --token         Figma Personal Access Token (or use FIGMA_PERSONAL_TOKEN env var)
-n, --nodes           Comma-separated list of node IDs
-s, --scale        Scale factor 1-4 (default: 2)
--format           Image format: png, jpg, svg, pdf (default: png)
--no-cache                 Do not use cache
--with-metadata            Save metadata JSON alongside images
--verbose                  Show verbose output

高级示例

# High-resolution export (scale=3)
mcp-figma-demo "https://www.figma.com/file/ABC123/..." \
  --nodes "1:2" \
  --scale 3 \
  --with-metadata

# Custom output directory
mcp-figma-demo "https://www.figma.com/file/ABC123/..." \
  --nodes "1:2" \
  --output ./my-exports

# Force refresh (ignore cache)
mcp-figma-demo "https://www.figma.com/file/ABC123/..." \
  --nodes "1:2" \
  --no-cache

文件命名

导出的文件采用以下格式命名：

{fileKey}_{nodeId}_{nodeName}.png
{fileKey}_{nodeId}_{nodeName}.json  # Metadata (if --with-metadata)

示例：

ABC123_1-2_login_screen.png
ABC123_1-2_login_screen.json

缓存

• API响应已缓存至 .cache/ 目录
• 默认TTL（生存时间）：24小时
• 在后续运行中会自动使用缓存
• 使用 --no-cache 强制进行一次新的API调用

速率限制

Figma API 有速率限制（第一级：每分钟10-20个请求）。此工具：

• 缓存API响应以减少请求
• ✅ 自动重试429错误
• ✅ 尊重 Retry-After 头部信息（或请求头）
• 批量处理多个节点，一次API调用即可完成

发展

# Run in development mode
pnpm dev

# Format code
pnpm format

# Lint code
pnpm lint

# Check code (format + lint)
pnpm check

项目结构

mcp-figma-demo/
├── src/
│   ├── cli/              # CLI implementation
│   ├── client/           # Figma API client & cache
│   ├── core/             # Core functionality
│   └── utils/            # Utilities
├── .cache/               # API response cache (gitignored)
├── output/               # Exported images (gitignored)
└── dist/                 # Compiled output (gitignored)

故障排除

“需要Figma令牌”

确保你已经设置了 FIGMA_PERSONAL_TOKEN 环境变量或传递 --token 选项。

“无效的Figma网址”

确保您的URL遵循以下格式：

• https://www.figma.com/file/{fileKey}/...
• https://www.figma.com/design/{fileKey}/...

“节点没有图片URL”

节点ID可能无效，或者文件中不存在该节点。请检查：

1. 节点ID是正确的（您可以通过在Figma中右键点击图层来获取它）
2. 您可以访问该文件

速率限制错误（429）

该工具会自动重试，但如果您发送了大量请求：

1. 让缓存发挥它的作用（不要使用 --no-cache （不必要地）
2. 在大批量导出之间等待几分钟

MCP服务器（第二阶段）

这个项目现在包含一个MCP（模型上下文协议）服务器，它允许像Claude这样的AI助手直接与Figma API进行交互。

MCP服务器功能

MCP服务器提供了三种用于人工智能交互的工具：

1. figma_export_image - 从Figma导出图像
2. figma_get_node_info - 获取详细的节点信息和层级结构
3. figma_list_exports - 列出之前导出的图像

启动MCP服务器

# Build the project first
pnpm build

# Start the MCP server
pnpm mcp

服务器在标准输入/输出（stdio）上运行，并使用模型上下文协议进行通信。

在Claude Desktop中配置MCP服务器

在您的Claude桌面配置文件中添加以下配置：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json

Windows： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "figma": {
      "command": "node",
      "args": ["/path/to/mcp-figma-demo/dist/mcp/index.js"],
      "env": {
        "FIGMA_PERSONAL_TOKEN": "your-figma-token-here"
      }
    }
  }
}

替换 /path/to/mcp-figma-demo 以及此项目的实际路径。

使用带有AI的MCP服务器

一旦配置完成，您可以要求Claude：

Export this Figma design: https://www.figma.com/file/ABC123/...?node-id=1-2

Get information about the nodes in this Figma file: https://www.figma.com/file/ABC123/...

List all previously exported Figma images

该人工智能将使用MCP工具与Figma进行交互，并提供结构化的响应。

MCP 工具详情

figma导出图像

从Figma导出图像并将其保存到本地。

参数：

• figmaUrl （必填）：Figma 文件 URL
• nodeIds （可选）：要导出的节点ID数组
• scale （可选）：缩放因子 1-4（默认值：2）
• format （可选）：图像格式 - png、jpg、svg、pdf（默认：png）
• outputDir （可选）：输出目录（默认：./output）
• withMetadata （可选）：保存元数据JSON（默认：true）
• useCache （可选）：使用缓存响应（默认：true）

返回值：

{
  "success": true,
  "fileKey": "ABC123",
  "nodeIds": ["1:2"],
  "outputDir": "./output",
  "exportedFiles": [
    {
      "image": "./output/ABC123_1-2_screen.png",
      "metadata": "./output/ABC123_1-2_screen.json",
      "nodeId": "1:2"
    }
  ],
  "message": "Successfully exported 1 image(s)"
}

获取figma节点信息

检索详细的节点信息，包括层级、位置和大小。

参数：

• figmaUrl （必填）：Figma 文件 URL
• nodeIds （可选）：节点ID数组
• useCache （可选）：使用缓存响应（默认：true）
• includeChildren （可选）：包含子节点（默认：true）
• maxDepth （可选）：最大树深度（默认：10）

返回值：

{
  "success": true,
  "fileKey": "ABC123",
  "fileName": "Design File",
  "lastModified": "2025-01-01T00:00:00Z",
  "nodes": [
    {
      "nodeId": "1:2",
      "hierarchy": {
        "id": "1:2",
        "name": "Login Screen",
        "type": "FRAME",
        "bounds": {
          "x": 0,
          "y": 0,
          "width": 375,
          "height": 812
        },
        "children": [...]
      }
    }
  ],
  "message": "Retrieved information for 1 node(s)"
}

figma_list_exports 翻译成中文是：“Figma 列表导出”

列出之前导出的图像及其元数据。

参数：

• outputDir （可选）：要列出的目录（默认：./output）
• fileKey （可选）：按文件键过滤

返回值：

{
  "success": true,
  "outputDir": "./output",
  "exports": [
    {
      "image": "./output/ABC123_1-2_screen.png",
      "metadata": "./output/ABC123_1-2_screen.json",
      "fileKey": "ABC123",
      "nodeId": "1:2",
      "nodeName": "screen",
      "exportedAt": "2025-01-01T00:00:00Z",
      "size": 123456
    }
  ],
  "count": 1,
  "message": "Found 1 exported image(s)"
}

未来计划

• 使用sharp实现的图片裁剪功能
• ⚙️ 配置文件支持
• 📝 使用配置文件进行批处理操作

许可证

Apache 2.0