figjam-mcp

figjam-context-mcp

一个本地 MCP 服务，可将 FigJam 白板转化为带来源引用的上下文，供大模型使用。 它通过 Figma REST API 读取白板，将便签、表格、图片和箭头归类为集群，并在回答问题时附上指向原始节点的链接。

此内容由针对公开演示白板的真实运行中工具调用及其输出呈现，使用的是 figjam-context-mcp 0.10.2 和 openai/gpt-4.1-mini。Figma 的 MCP 服务（use_figma）执行了编辑。

为什么

研讨会白板记录了研究笔记、决策和待解决的问题，但大模型无法读取画布。截图和 PDF 导出会丢失表格、箭头方向以及来源链接。此服务会保留白板结构，并为每个回答引用其所依据的节点。

与 Figma 的 MCP 服务对比

Figma 官方 MCP 服务可读取 FigJam 白板或节点及其图片（get_figjam），也可编辑白板（use_figma）。此服务则将研讨会白板转化为助手可以引用和跟踪的上下文：

• 大型白板按区块读取，并提供概览、大小受限的页面和搜索
• 精简概览中包含来源 ID，完整摘录和回答引用中包含 Figma 链接
• 逐行读取表格
• 保存本地快照，并通过 diff_board 查看更改
• 在凭据到达缓存、输出或模型之前，明确对其进行脱敏
• 使用你配置的视觉模型生成图片描述

两者可以协同使用：在上面的演示中，Figma 的服务编辑白板，而此服务报告了更改。

工具

工具	功能	大模型调用
ingest_board	读取白板，将内容归类为集群，并保存本地快照。重新读取时会复用未更改的集群；focusNodeIds 用于选择优先解读图片的区块。	在 balanced（默认）和 max_quality 模式下
get_board_context	读取已保存的上下文；读取大型区块时会自动使用精简的来源 ID 行；detail: "full" 会返回完整摘录和 Figma 链接。还支持主题搜索和分页。	否
answer_from_board	根据最相关的摘录回答一个具体问题（数字、状态或决策），并提供节点级引用；证据不足时会给出相应结果。不适用于整张白板的摘要。	是
diff_board	比较两个快照，列出新增、移除和更改的集群、节点、表格单元格及箭头。	否
diagnose_llm_config	使用小型文本和图片 JSON 检查测试已配置的模型。	是

快速开始

需要 Node.js 22.12 或更高版本。

1. 在 Settings → Security → Personal access tokens 中创建 Figma 个人访问令牌，并授予 file_content:read 权限。令牌所属账号需要有权访问该白板。
2. 可选：在 openrouter.ai/keys 创建 OpenRouter 密钥。此密钥可启用图片解读、answer_from_board 和 diagnose_llm_config。如果没有密钥，请使用 ingestMode: "max_speed"，并搭配 get_board_context 和 diff_board。
3. 根据下方客户端对应的示例添加服务。使用 @latest 和 --prefer-online 后，即使包元数据已缓存，npx 也会在每次启动时检查注册表中的最新版本（npm 配置）。

Claude Code

claude mcp add figjam-context -e FIGMA_ACCESS_TOKEN=your-figma-token -e LLM_BASE_URL=https://openrouter.ai/api/v1 -e LLM_API_KEY=your-openrouter-key -- npx -y --prefer-online figjam-context-mcp@latest

对于较长的摄取任务，请在启动 Claude Code 的环境中设置 MCP_TOOL_TIMEOUT=300000，并在服务环境中设置 INGEST_BOARD_VISION_BUDGET_MS=270000，为摄取任务的其余部分留出约 30 秒时间（Claude Code 环境变量）。

Codex CLI 和 ChatGPT 桌面应用

将以下内容添加到 ~/.codex/config.toml；应用、CLI 和 IDE 扩展共用此配置（OpenAI MCP 设置）：

[mcp_servers.figjam-context-mcp]
enabled = true
command = "npx"
args = ["-y", "--prefer-online", "figjam-context-mcp@latest"]
startup_timeout_sec = 30
default_tools_approval_mode = "approve"

[mcp_servers.figjam-context-mcp.env]
FIGMA_ACCESS_TOKEN = "your-figma-token"
LLM_BASE_URL = "https://openrouter.ai/api/v1"
LLM_API_KEY = "your-openrouter-key"

如果没有 default_tools_approval_mode = "approve"，ChatGPT 可能会要求批准，或中止具有外部影响的工具调用；启用此设置后，客户端在将看板内容发送给模型提供方之前不会询问，因此请使用 max_speed，并避免对机密看板使用 answer_from_board。

对于较长时间的摄取，在 [mcp_servers.figjam-context-mcp] 下设置 tool_timeout_sec = 300，并在其 env 表中设置 INGEST_BOARD_VISION_BUDGET_MS = "270000"，为摄取的其余部分留出约 30 秒（OpenAI 超时选项）。

GitHub Copilot CLI

将以下内容添加到 ~/.copilot/mcp-config.json（Copilot CLI MCP 设置）：

{
  "mcpServers": {
    "figjam-context": {
      "type": "local",
      "command": "npx",
      "args": ["-y", "--prefer-online", "figjam-context-mcp@latest"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "your-figma-token",
        "LLM_BASE_URL": "https://openrouter.ai/api/v1",
        "LLM_API_KEY": "your-openrouter-key"
      },
      "tools": ["*"]
    }
  }
}

对于较长时间的摄取，在 ~/.copilot/mcp-config.json 中为服务设置 "timeout": 300000，并在其 env 中设置 "INGEST_BOARD_VISION_BUDGET_MS": "270000"，为摄取的其余部分留出约 30 秒（已使用 600000 ms 超时进行测试）。

VS Code

将以下内容添加到工作区中的 .vscode/mcp.json，或为你的配置文件打开 MCP: Open User Configuration。VS Code 使用 servers 和 type: "stdio"（VS Code MCP 配置）：

{
  "servers": {
    "figjam-context": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "--prefer-online", "figjam-context-mcp@latest"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "your-figma-token",
        "LLM_BASE_URL": "https://openrouter.ai/api/v1",
        "LLM_API_KEY": "your-openrouter-key"
      }
    }
  }
}

对于较长时间的摄取，请使用 Local harness，在 mcp.json 中为每个服务设置 "timeout": 300000，并在其 env 中设置 "INGEST_BOARD_VISION_BUDGET_MS": "270000"（比超时时间少约 30 秒）；#343135 指出，Copilot harness 中的远程 HTTP 工具调用（1.142 中的默认方式）会忽略该超时，并在约 180 秒后停止，而 Local harness 会遵守该超时。

其他 MCP 客户端

对于接受 mcpServers 的客户端，将以下内容添加到其 MCP 配置中：

{
  "mcpServers": {
    "figjam-context": {
      "command": "npx",
      "args": ["-y", "--prefer-online", "figjam-context-mcp@latest"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "your-figma-token",
        "LLM_BASE_URL": "https://openrouter.ai/api/v1",
        "LLM_API_KEY": "your-openrouter-key"
      }
    }
  }
}

如果客户端支持配置工具超时，请根据其文档中的设置将超时调高至约 300 秒，并在服务环境中设置 INGEST_BOARD_VISION_BUDGET_MS=270000，比超时时间少约 30 秒。 Cursor 不提供可配置的超时：其 IDE 允许约 60 分钟，而 ACP/CLI 调用即使有进度提示也会在 60 秒后停止，因此在此路径上请保留默认图像预算（Cursor 支持）。

然后让你的助手摄取一个看板 URL，例如 “摄取 https://www.figma.com/board/FILE_KEY/Name 并列出尚未解决的问题。” 后续每次调用中的 boardId 都是该 URL 中的文件键。要总结看板，助手会调用 ingest_board，然后不带参数调用 get_board_context；其第一页会列出最大的分区，并在页面大小限制内提供带有 ID 的分区概览，随后通过将这些分区的 ID 作为 nodeIds 传入，读取最大的分区。 如果较大的 nodeIds 读取中，第一页完整内容会导致部分摘录未被读取，系统会自动按分区分组，改用简短的源 ID 行。limit 仅适用于完整视图；即使提供了该参数，概览也会忽略它。要读取完整文本及其 Figma 链接，请使用相同的 boardId 和 snapshotId，将该行的 ID 传入 nodeIds，并设置 detail: "full"。对于表格行，请使用其表格 ID。 不属于任何分区的内容（例如零散便笺和表格）会通过 outsideSections: true 返回。

所有设置：配置。 问题：故障排除。

工作原理

1. 读取。 每次调用 ingest_board 时，都会通过 Figma REST API 下载画板。get_board_context 和 answer_from_board 会读取已保存的快照，不会发起新请求。
2. 规范化。 节点会转换为文本、表格单元格、图片和连接线，并保留其页面和分区信息。表格按行读取：行和列由单元格 ID 确定，每一行成为一条摘录。
3. 聚类。 按照考虑旋转因素的距离，将邻近节点分组。组之间的箭头会成为有向关系。如果页面上存在某个箭头的一端，或其周围的分区、框架或组，该箭头就会出现在上下文中。没有模型标签的聚类会以其所属分区命名。
4. 解读。 在 balanced 模式下，包含图片的聚类，或不含任何文本的绘图，会在 40 秒预算内通过视觉模型生成摘要；无论文本聚类多短，都会保留提取出的文本。只有剩余时间足以处理某个聚类时才会开始处理；未完成的聚类会在下一次导入时继续处理。使用 focusNodeIds 时，指定分区、框架或节点中的图片会优先处理。在 max_quality 模式下，一次导入会在 40 秒的图片处理预算内解读几十个聚类（在约有 300 个聚类的画板上，使用 3 个并行请求测得为 20–35 个）；下一次导入会继续处理，每次都会产生一次 Tier 1 文件下载费用，而 focusNodeIds 会决定处理顺序。
5. 提供服务。 快照会保存到私有本地缓存中。搜索时会优先选择包含更多问题词语的摘录。 get_board_context 会搜索缓存（对原始文本、表格行和名称使用 BM25），answer_from_board 会通过引用作答，diff_board 会比较快照。首次调用 get_board_context 返回的页面包含有大小限制的分区概览及其 ID；传入页面、分区、框架或组的 ID 作为 nodeIds，即可读取其中的所有内容；一次调用传入多个 ID 时，会按请求顺序轮流处理。使用默认的 detail: "auto" 时，如果读取多个不同 ID 或一个容器，而第一页完整内容会导致部分摘录无法读取，则会改用简洁概览。文本会缩短为统一的 50–120 个字符前缀，并附加 …；摘要由宿主编写。主题搜索、outsideSections、单个叶节点／表格／单元格 ID 和小型容器会保留完整内容。文本 content 是易读的页面内容；structuredContent 则会将每条摘录仅存放一次：概览视图中位于 overview.text（evidence 和 clusters 为空），完整视图中位于 evidence。在完整摘录中，只有响应中的 snapshotId 会被继承：缺少 chunkIndex 时默认为 0，缺少 truncated 或 modelDerived 时默认为 false；这些标志不会从聚类继承。

模型与成本

默认预设 student-free 使用 OpenRouter 免费模型：文本和图像会发送到 openrouter/free，由它选择支持结构化输出的免费模型（处理图像时，还需支持图像）。 免费默认方案仅尽力而为：免费模型会变动，也可能触发速率限制或超时。对 openrouter/free 或 openrouter/auto 的请求若因服务商错误而失败，会再发送一次， 因为路由器可能会选择其他模型。图像会发送到最长边不超过 1,024 px 的模型； 更大的图像会在本地缩小。

• OpenRouter 允许免费模型每分钟发送 20 次请求、每天发送 50 次请求； 购买至少 10 个额度后，每天可发送 1,000 次请求 （限制）。
• Figma 会按席位和套餐限制请求 （速率限制）。文件 下载和图像渲染属于 Tier 1：付费套餐中的 Dev 和 Full 席位每分钟可发送 10–20 次请求；View 和 Collab 席位以及 Starter 套餐中的文件每月最多可发送 20 次请求。每次 ingest_board 调用都会下载一个文件，因此 View 或 Collab 席位每月约可执行 20 次提取。图像则来自图像填充，属于 Tier 2，每次 提取发送一个请求，每分钟至少可发送 5 次请求。对于不含图像的绘图，以及单张 图像的备用处理方式，会使用渲染；一次渲染请求最多涵盖 18 个节点。 max_speed 不需要这些请求。
• LLM_BASE_URL 可接受任何兼容 OpenAI 的端点；对于付费模型，请设置 LLM_TEXT_MODELS、LLM_FAST_TEXT_MODELS 和 LLM_VISION_MODELS，例如 将这三项都设为 openai/gpt-4.1-mini（需支付服务商费用）。
• 每次更改模型后都运行 diagnose_llm_config。它会使用合成输入检查 JSON 回复 和图像理解能力。

隐私

• 服务只读取 Figma 内容，不会更改画板。
• balanced 和 max_quality 提取会将画板文本和图像（原图或 渲染图）发送给配置的大模型服务商。answer_from_board 会发送问题和选定 的摘录。使用 get_board_context 和 diff_board 的 max_speed 不会向 大模型服务商发送任何内容。
• 快照会保存在你本机上按用户隔离的私有缓存中。删除缓存目录即可移除快照。
• 在凭据传到缓存、工具输出或大模型服务商之前，会对 Passwort: … 等明确的凭据 或 API 密钥进行脱敏 （FIGJAM_MCP_REDACT_CREDENTIALS）。这只是 一道安全防线，并非万无一失：图像不会脱敏，因此请勿在画板上放置凭据。
• 请将令牌保存在客户端环境中。作为工具参数传入的令牌可能会出现在客户端日志中。

限制

• 默认情况下，每次提取的图像解读时长为 40 秒；大型画板需要多次提取， 才能解读所有图像集群。
• 如果客户端取消提取（例如超时设为 60 秒后取消），将不会收到部分结果。
• 免费模型仅尽力而为。引用会显示答案的来源，但不能证明结论正确。
• 搜索基于词面匹配；不含共同词语的同义词无法匹配。
• 仅支持本地 stdio；不支持托管或多用户模式。

测量结果：评估。

开发

git clone https://github.com/ecestnrkl/figjam-mcp.git
cd figjam-mcp
npm ci
cp .env.example .env    # add your tokens
npm run check           # typecheck, tests, build, package validation
npm run package:smoke   # install the packed package and exercise all tools
npm run eval:retrieval  # offline retrieval and diff evaluation
npx --prefer-online @modelcontextprotocol/inspector --config inspector.config.json

请参阅 CONTRIBUTING.md 和更新日志。

许可证

MIT © 2026 ecestnrkl