内容
# figma-comments-mcp
[](https://github.com/junsimon/figma-comments-mcp/actions/workflows/ci.yml)
[](./LICENSE)
[](https://nodejs.org)
[](https://modelcontextprotocol.io)
一个本地的MCP服务器，允许Claude（或任何MCP客户端）**读取、理解和操作Figma和FigJam中的评论** —— 这是官方Figma Dev Mode MCP无法提供的功能。
适用于 **Figma设计文件** (`figma.com/design/…`) 和 **FigJam面板** (`figma.com/board/…`)，因此它适用于整个项目的设计评审、设计质量保证和协作中间过程 —— 工作坊、头脑风暴、回顾和研讨会，其中思考过程体现在贴纸和框架上的固定评论中。
**为什么存在这个项目：** 客户端、评审人和工作坊参与者将大部分反馈作为评论固定在画布上。AI助手可以读取设计本身 —— 层、截图、代码 —— 但不能读取这些固定的评论，因此反馈永远无法真正融入工作中。这个服务器填补了这个空白：Claude读取评论 **并准确知道每个评论指向哪一层或哪个贴纸**，因此 _"make this blue"_ 变为 _"make `Checkout / CTA Button` blue."_
官方Figma MCP为AI助手提供了设计树、截图、变量和代码，但 **不包括评论**。客户端、评审人和工作坊参与者将大部分反馈作为评论固定在画布上。这个服务器封装了Figma REST评论API，并且关键在于 **解析每个评论固定的节点** —— 设计文件中的一层或FigJam面板中的一个贴纸/形状/部分（名称 + 面包屑路径 + 节点ID）—— 因此诸如 _"make this blue"_ 的反馈变为可操作的： _"comment on `Checkout / CTA Button` (node 1:360): make this blue."_
它与官方Figma MCP一起使用 —— 官方Figma MCP读取设计结构并写入设计变更；这个项目添加了缺失的评论层。
```
┌─────────┐ 读取评论 ┌──────────────────────┐
│ Claude │ ───────────────────▶ │ figma-comments-mcp │ ──▶ Figma REST API
│ （MCP │ │ （此仓库） │ /v1/files/:key/comments
│ 客户端） │ ◀─────────────────── └──────────────────────┘
│ │ 读取/写入设计 ┌──────────────────────┐
│ │ ◀──────────────────▶ │ Figma Dev Mode MCP │ ──▶ Figma （官方）
└─────────┘ └──────────────────────┘
```
## 内容
- [工具列表](#工具列表)
- [示例输出](#示例输出)
- [评论 → 节点映射的工作原理](#评论-→-节点映射的工作原理)
- [快速开始](#快速开始)
- [使用MCP客户端注册](#使用MCP客户端注册)
- [CLI（用于调试）](#CLI（用于调试）)
- [配置参考](#配置参考)
- [开发](#开发)
- [贡献](#贡献) · [安全](#安全) · [许可证](#许可证)
## 工具列表
**读取（始终可用）：**
| 工具 | 功能 |
|---|---|
| `get_comments_summary` | 统计（总数/打开/已解决），按目标页面/框架分组的打开线程，每个打开线程的摘要。 |
| `list_comments` | 所有线程，分类，每个线程都包含其目标节点。默认情况下仅限打开的线程。 |
| `get_comment_thread` | 一个完整的线程（根 + 回复 + 反应 + 已解决状态 + 目标节点）。 |
| `render_comment_target` | 渲染评论固定的节点（或明确的 `node_id`）并返回图像，以便助手可以看到它。 |
**写入（仅当 `FIGMA_ENABLE_WRITES=true` 时，并且默认为 `dry_run` 预览）：**
| 工具 | 功能 |
|---|---|
| `reply_to_comment` | 回复线程（例如“已完成 - 已将按钮更改为蓝色”）。 |
| `react_to_comment` | 添加表情符号反应（默认为 `:white_check_mark:`）作为轻量级“已处理”标记。 |
| `post_comment` | 在节点或坐标处放置新的固定评论。 |
> **分辨率限制：** Figma REST API **没有解析评论的端点** —— `resolved_at` 只能在Figma UI中设置。使用回复或 `:white_check_mark:` 反应作为机器可写的“已处理”信号。
## 示例输出
`get_comments_summary` 返回一个概览 —— 统计数据、按位置分组的打开线程和每个线程的摘要：
```
评论：12 个总数，4 个打开，8 个已解决。
按目标分组的打开线程：
- Checkout / Payment: 2
- Home / Hero: 1
- （未固定）：1
打开线程：
#3 Checkout / CTA Button: make this blue
#7 Checkout / Card field: the label is cut off on mobile
#9 Home / Hero: can we try a lighter headline?
#11 （未固定）：overall looks great, ship it
```
`list_comments` / `get_comment_thread` 返回完整的线程，每个线程都与其固定的图层绑定：
```
#3 [OPEN] @jane 2026-06-10
目标：Checkout / CTA Button （节点 1:360）
"make this blue"
└ reply @simon: "on it"
✅ x1
```
`(node 1:360)` 是官方Figma MCP无法提供的部分：它准确地告诉助手反馈针对哪个图层。
## 评论 → 节点映射的工作原理
每个评论都带有 `client_meta`，有四种形式：
- **FrameOffset / FrameOffsetRegion** —— 具有 `node_id` → 直接查找节点名称、类型和面包屑路径（Figma中的图层，FigJam中的贴纸/形状/部分）。
- **Vector / Region** —— 纯粹的绝对坐标 → 服务器获取文件的节点树并返回 **最深的节点，其边界框包含该点**，标记为 `[inferred]` 以便您知道映射是启发式的。
文件树仅获取一次并缓存在内存中（TTL，默认为 60 秒），因此丰富化不会为每个评论重新获取。
## 快速开始
**要求：** [Node](https://nodejs.org) 20+ 和 npm。
### 1. 创建Figma个人访问令牌
Figma → **设置 → 安全 → 个人访问令牌**。选择这些范围：
- `file_comments:read` —— 读取评论和反应（必需）
- `file_content:read` —— 读取节点树以丰富内容 + 渲染图像（必需）
- `file_comments:write` —— 发布回复/反应/评论（仅当启用写入时）
### 2. 安装和构建
```bash
git clone https://github.com/junsimon/figma-comments-mcp.git
cd figma-comments-mcp
npm install
npm run build
```
### 3. 提供令牌
复制 `.env.example` 到 `.env` 并设置 `FIGMA_TOKEN`:
```bash
cp .env.example .env
# 编辑 .env 并粘贴您的令牌
```
服务器和CLI自动从项目根目录加载 `.env`。（或者，通过MCP客户端的 `env` 块传递 `FIGMA_TOKEN` —— 参见下文。） `.env` 被git忽略。
### 4. 使用CLI验证
```bash
node dist/cli.js "https://www.figma.com/design/<KEY>/<name>" --summary # Figma 设计文件
node dist/cli.js "https://www.figma.com/board/<KEY>/<name>" --summary # FigJam 面板
```
您应该看到评论计数和每个打开线程的摘要。 裸文件密钥也可以使用， `/design/`、 `/board/`、 `/file/` 和 `/proto/` URL 都被接受。
## 使用MCP客户端注册
服务器通过 **stdio** 使用MCP。对于Claude Code，请运行：
```bash
claude mcp add figma-comments \
-e FIGMA_ENABLE_WRITES=false \
-- node /absolute/path/to/figma-comments-mcp/dist/index.js
```
… 或将其添加到您的MCP配置中（ `.mcp.json` / `claude_desktop_config.json` / 等）：
```json
{
"mcpServers": {
"figma-comments": {
"command": "node",
"args": ["/absolute/path/to/figma-comments-mcp/dist/index.js"],
"env": {
"FIGMA_TOKEN": "<your token>",
"FIGMA_ENABLE_WRITES": "false"
}
}
}
}
```
> **将 `/absolute/path/to/figma-comments-mcp` 替换为实际路径** —— 该字符串是一个占位符，而不是字面值。 如果您直接复制它，客户端将启动服务器时出现 `Error: Cannot find module '/absolute/path/to/figma-comments-mcp/dist/index.js'` 错误。 运行 `pwd` 获取克隆仓库的路径，并确保您已构建它（ `npm run build`），以便 `dist/index.js` 存在。 同样适用于上面的 `claude mcp add` 命令。
如果您将令牌保留在 `.env` 中，则可以省略上面的配置中的 `FIGMA_TOKEN`。 将 `FIGMA_ENABLE_WRITES` 设置为 `true` 以公开写入工具 - 即使如此，每个写入操作都默认为 `dry_run` 预览，因此助手必须传递 `dry_run:false` 才能实际修改共享文件。 在注册后重启客户端。
## CLI（用于调试）
```bash
node dist/cli.js "<figma file url>" # 丰富的评论块（仅限打开）
node dist/cli.js "<figma file url>" --include-resolved # 包括已解决的
node dist/cli.js "<figma file url>" --summary # 计数 + 摘要
node dist/cli.js "<figma file url>" --json # 原始丰富JSON
```
在开发过程中，您可以使用 `npm run cli -- "<url>"` 跳过构建（通过 `tsx`）。
## 配置参考
| 环境变量 | 默认值 | 目的 |
|---|---|---|
| `FIGMA_TOKEN` | — （必填） | 个人访问令牌。 |
| `FIGMA_ENABLE_WRITES` | `false` | 注册写入工具。 |
| `FIGMA_TREE_TTL_MS` | `60000` | 内存文件树缓存TTL。 |
| `FIGMA_TREE_DEPTH` | `4` | 为富集而获取的最大节点树深度。 限制有效载荷，以免大文件断开连接。 `0` = 无限制。 |
所有变量都可以在环境或 `.env` 中设置。
## 开发
```bash
npm test # vitest — URL解析、丰富命中测试、线程
npm run typecheck # tsc --noEmit
npm run dev # 使用tsx从源代码运行服务器
npm run cli -- "<url>" # 使用tsx从源代码运行CLI
```
CI（GitHub Actions）在 Node 20 上运行类型检查、构建和测试。
## 贡献
欢迎贡献 - 请参阅 [CONTRIBUTING.md](./CONTRIBUTING.md)。 请勿提交机密信息或在问题/拉取请求中粘贴令牌。
## 安全
将您的令牌保留在 `.env` （gitignored）中，授予它所需的最小范围，并撤销任何泄露的令牌。 服务器仅将令牌发送到Figma的API。 发现漏洞？ 请发送电子邮件至 simonjun@simonjun.cz 而不是公开问题。
## 许可证
[MIT](./LICENSE) © Šimon Jůn
