custom-figma-mcp

一个轻量级的本地 MCP (Model Context Protocol) 服务器，为 AI 编码代理（如 OpenCode）提供对 Figma 文件的结构化、只读访问——文件层级、节点属性和渲染图像——无需依赖 Figma 的托管/远程 MCP 集成。

为什么会有这个项目

Figma 官方的远程 MCP 服务器仅对列入白名单的 Client ID 开放，这对想要自己搭建代理工具的个人开发者来说并不现实。本项目绕开了这一限制，直接使用个人访问令牌与 Figma 的公开 REST API 通信，并通过基于 stdio 的标准 MCP 工具接口将能力暴露给代理。

Related MCP server: figma-mcp

架构

OpenCode (MCP client)
      │  stdio (JSON-RPC)
      ▼
custom-figma-mcp (this server)
      │  HTTPS + X-Figma-Token
      ▼
Figma REST API (api.figma.com/v1)

该服务器是一个单独的 Node.js 进程，它会：

1. 启动并使用 @modelcontextprotocol/sdk 在 stdio 上注册自身。

2. 通过 ListToolsRequestSchema 向 MCP 客户端（OpenCode）通告一组固定的工具。

3. 通过 CallToolRequestSchema 执行工具调用，并将其代理到 Figma 的 REST API，同时把你的个人访问令牌附加为请求头。

4. 将结构化 JSON（或图像 URL）返回给调用方代理。

由于它永远只会携带只读作用域令牌发起 GET 请求，因此无法修改、评论或删除 Figma 中的任何内容——它在设计上严格只读。

暴露的工具

get_figma_file_structure

返回文件的页面/画框层级结构，并限制深度，以避免倾倒整棵节点树（大型文件中的节点可能多达数万个）。

输入：

{ "fileKey": "string", "depth": 2 }

映射到： GET /v1/files/:fileKey?depth=:depth

get_figma_node_details

获取指定节点 ID 的完整属性——自动布局配置、内边距/间距值、填充、描边、排版、约束、组件属性等。这是用于生成准确代码的主要工具。

输入：

{ "fileKey": "string", "nodeIds": ["1:2", "104:15"] }

映射到： GET /v1/files/:fileKey/nodes?ids=1:2,104:15

get_figma_node_image

将指定节点渲染为 PNG，并返回一个临时的签名 URL，可用于将生成的代码与设计进行视觉交叉核对。

输入：

{ "fileKey": "string", "nodeId": "104:15", "scale": 2 }

映射到： GET /v1/images/:fileKey?ids=104:15&scale=2

为什么拆分为三个工具（而不是一个）

Figma 文件可能非常庞大——一次不带深度限制的 GET /files/:key 调用就能返回数 MB 的深层嵌套 JSON，瞬间撑爆 LLM 的上下文窗口。将接口拆分成三个有针对性的工具，可以让代理：

1. 先获取轻量级大纲（get_figma_file_structure），确定相关的画框/节点。

2. 只深入查看它需要的特定节点（get_figma_node_details）。

3. 仅在需要视觉确认时，选择性地渲染图像（get_figma_node_image）。

这正像人类开发者检查设计的方式——先浏览，再放大——而不是一次性把整个文件全部读进来。

身份验证

身份验证使用具有 file_content:read 权限范围的 Figma 个人访问令牌（PAT）。该令牌从本地 .env 文件加载（绝不硬编码），并作为 X-Figma-Token 请求头附加到每个出站请求上。除了直接发送到 api.figma.com 的请求外，令牌绝不会离开本地机器。

错误处理

所有工具处理程序都包裹在 try/catch 中。失败时（文件 key 无效、无访问权限、触发限流等），服务器会返回符合 MCP 规范的错误响应：

{
  "content": [{ "type": "text", "text": "Figma API Error: <details>" }],
  "isError": true
}

这让调用方代理能够看到实际的失败原因，而不是无声地崩溃。

项目结构

custom-figma-mcp/
├── index.js        # server entrypoint — tool definitions + handlers
├── package.json    # dependencies, "type": "module" for ESM imports
├── .env            # local only — holds FIGMA_PAT, never committed
└── .gitignore

本地开发

直接运行服务器进行调试（它通过 stdio 通信，因此你不会看到典型的 HTTP 服务器日志）：

node index.js

实际上，你不需要手动运行它——OpenCode 会根据 opencode.json 中定义的 command 将它作为子进程启动。

扩展此服务器

要添加新工具：

1. 将其 schema 添加到 ListToolsRequestSchema 返回的 tools 数组中。

2. 在 CallToolRequestSchema 处理程序内添加一个匹配的 if (name === "...") 分支。

3. 将其映射到 figmaApi 下对应的 Figma REST 端点（figmaApi 是一个预配置了基础 URL 和身份验证请求头的 axios 实例）。

让新工具保持只读且范围明确——尽可能避免倾倒未经筛选的完整 API 响应，以控制代理的上下文消耗。