Figma MCP Server

Figma MCP 服务（Apify Actor）

Model Context Protocol（MCP）服务，可向 AI 助手（Cursor、Claude、自定义 Agent）提供 Figma REST API 功能。在 Apify 平台上作为长期运行的 Web 服务运行（待机 / 容器 URL），也可通过 apify run 在本地运行。

功能

• 文件分析 — 结构、元数据、样式、深度受限的树
• 组件 — 列表、详情、使用情况
• 资源 — 导出节点（PNG、SVG、PDF、JPG）
• 评论 — 读取和创建
• 项目 / 团队 — 列表和元数据
• 用于引导工作流的 MCP 资源和提示词

身份验证

个人访问令牌（默认）

建议个人使用。在 Actor 输入中设置 figmaAccessToken（或在环境变量中设置 FIGMA_ACCESS_TOKEN）。

• 生成令牌：Figma → Settings → Security → Personal access tokens
• API 请求头：X-Figma-Token
• 设置 PAT 后，API 调用将禁用 OAuth（且 /oauth/* 路由会返回错误）。

OAuth 2.0（可选 — 团队 / 共享文件）

当你省略 figmaAccessToken 并提供 Figma OAuth 应用时使用：

输入	用途
oauthClientId	来自 Figma → Developers → Apps
oauthClientSecret	同一应用
oauthRedirectUri	在应用中注册的准确重定向 URL，例如 https://<your-run>.runs.apify.net/oauth/callback
oauthScopes	可选；以逗号分隔的权限范围。必须是应用已配置权限范围的子集。默认包括 file_content:read、file_content:write、file_comments:read、file_comments:write。

流程

1. 填写 OAuth 字段且不设置 PAT，启动 Actor。
2. 在浏览器中打开 GET https://<container-url>/oauth/authorize（使用普通浏览器，不要使用内嵌 WebView；Figma 要求）。
3. 授权后，Figma 会重定向到 /oauth/callback；令牌会存储在本次运行的默认键值存储（FIGMA_OAUTH_SESSION）中，并在即将过期时刷新。

令牌交换使用 Figma 文档中列出的端点（https://api.figma.com/v1/oauth/token 和 .../oauth/refresh）。授权码很快就会过期 — 请及时完成重定向。

要求

• Node.js ≥ 20
• Apify 账户（用于云端）
• Figma PAT 和 / 或 OAuth 应用

快速开始（Apify Cloud）

npm install
apify login
apify push

在 Apify Console 中打开 Actor，设置输入（至少设置 figmaAccessToken），根据模板要求以Web 服务 / 长期运行模式启动，然后使用本次运行的容器 URL。

部署参考：apify push 会构建并发布；请参阅 Apify CLI。

配置（输入）

参数	类型	默认值	描述
figmaAccessToken	string	—	PAT（推荐）。 设置后，将用于所有 Figma API 调用。
port	integer	8080	HTTP 监听端口（Apify 可能会通过 web_server_port 覆盖）。
oauthClientId	string	—	OAuth 应用客户端 ID（仅在不使用 PAT 时需要）。
oauthClientSecret	string	—	OAuth 应用密钥（机密输入）。
oauthRedirectUri	string	—	必须与 Figma 应用的重定向 URI 完全一致。
oauthScopes	string	—	可选的权限范围覆盖项（以逗号分隔）。
maxConcurrentRequests	integer	10	预留 / 未来用途。
enableCaching	boolean	true	缓存来自 Figma 的 GET 响应。

本地 / CLI 输入文件示例（apify run）：

{
  "figmaAccessToken": "figd_...",
  "port": 8080
}

HTTP API

方法	路径	描述
GET	/	服务信息和端点列表
GET	/health	存活状态；包含 auth_mode：pat | oauth | pending_oauth、figma_authenticated
POST	/mcp	MCP JSON-RPC 2.0（此服务的主要传输方式）
GET	/oauth/authorize	启动 OAuth（浏览器）；设置了 PAT 时禁用
GET	/oauth/callback	OAuth 重定向处理程序

Apify MCP 路径： .actor/actor.json 将 webServerMcpPath 设置为 /mcp。你的 MCP 客户端 URL 通常为：

https://<container-id>.runs.apify.net/mcp

（使用运行页面中的 Container URL，并在末尾添加 /mcp。）

Cursor IDE

1. 部署并启动 Actor；复制运行页面中的 Container URL（状态为 RUNNING 时）。
2. 编辑 ~/.cursor/mcp.json（Windows/Linux 上的路径有所不同，请参阅 Cursor 文档）。

示例（远程 HTTP MCP——请根据你的 Cursor 版本调整为其预期格式）：

{
  "mcpServers": {
    "figma-mcp-standby": {
      "url": "https://YOUR_RUN_ID.runs.apify.net/mcp"
    }
  }
}

注意

• mcp.json 中的 env.APIFY_TOKEN 不会传递给此 Node 进程；它不能替代 Figma 身份验证。请在 Actor 输入中使用 figmaAccessToken（或 OAuth）。
• Container URL 每次运行都会变化，运行结束后便会失效；新运行后请更新 mcp.json 并重启 Cursor。
• 如果连接失败，请使用 Cursor → Output → MCP 并运行 curl https://.../health。

Claude Desktop / 其他客户端

使用客户端支持的方式连接远程 MCP URL（例如，使用 mcp-remote 指向 https://.../mcp）。路径和查询参数取决于客户端版本。

本地开发

npm install
apify run

也可以在自行注入环境变量/输入的情况下，使用 Node 运行入口：

export FIGMA_ACCESS_TOKEN="figd_..."
node src/main.js

检查健康状态（端口来自日志或输入）：

curl -s http://localhost:8080/health | jq .

MCP initialize 示例：

curl -s -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'

项目结构

figma_mcp_actor/
├── .actor/
│   ├── actor.json           # Apify Actor metadata (incl. webServerMcpPath: /mcp)
│   ├── input_schema.json
│   ├── output_schema.json
│   └── dataset_schema.json
├── src/
│   ├── main.js              # Express app, /mcp, /oauth/*, Apify bootstrap
│   ├── figma/
│   │   ├── auth.js          # PAT + OAuth token exchange, refresh, KV hook
│   │   └── client.js        # Figma REST wrapper
│   ├── oauth/
│   │   └── persist.js       # Apify KV: FIGMA_OAUTH_SESSION
│   ├── mcp/                 # Protocol, handlers, server
│   ├── tools/
│   ├── resources/
│   └── prompts/
├── Dockerfile
├── package.json
└── README.md

MCP 工具（概览）

包括（名称在代码中可能略有不同）：文件分析（analyze_file、get_file_structure 等）、组件（list_components 等）、导出（export_node 等）、评论（get_comments、create_comment 等）、设计修改辅助工具，以及资源（figma://file/... 等）和常见任务的提示词。

限制

• REST 与 Plugin API——深入的设计写入可能需要使用 Plugin API；此 Actor 会在支持的情况下使用 REST。
• Apify 临时 URL——每次运行都会生成新的基础 URL，除非采用稳定的托管方案。
• OAuth——每次运行只存储一个会话（KV）；单个进程不支持多用户并发 OAuth。

脚本

npm run lint
npm run lint:fix
npm run format

许可证

ISC

更新日志

0.2

• 支持可选的 OAuth 2.0（Figma 授权码 + 刷新）；设置 PAT 时仍默认使用 PAT。
• 提供 /oauth/authorize 和 /oauth/callback；会话保存在默认 KV（FIGMA_OAUTH_SESSION）中。
• 输入：oauthRedirectUri、oauthScopes。
• 健康状态 JSON：auth_mode、figma_authenticated。

0.1 / 0.0.1

• 初始 MCP + Figma REST 集成、PAT、长时间运行的服务、/mcp JSON-RPC。

---

参考： Apify Actors · Figma REST API · Model Context Protocol