Claude Code MCP Figma 配置与故障排查
连接 Claude Code 与 Figma 远程 MCP，完成授权并测试单个画框；逐项排查权限、链接与响应故障。
稳定连接 Claude Code 与 Figma 的方法
最省事且受官方支持的方式，是安装 Claude Code 官方 Figma 插件，并使用 Figma 托管的远程 MCP 服务器。完整流程包括安装插件、重启 Claude Code、在浏览器中完成授权、用 /mcp 查看连接状态，再拿一个准确的画框链接做小范围测试。最后一步不能省：显示“已连接”只说明传输与账号握手成功，并不能证明当前账号有权读取目标文件，也不能证明链接指向了有效的设计上下文。
除非组织明确要求使用桌面端点，否则优先选择官方插件与远程服务器。它的工具覆盖更完整，也不要求某个 Figma 文件始终在桌面应用中打开。
可靠的配置应同时满足三点：/mcp 显示 Figma 已连接、授权账号能够打开文件、Claude Code 可以概括指定画框。
先让 Claude Code 列出组件、字体、颜色与间距，不要一开始就改代码。这样既能暴露上下文缺失，也不会在测试阶段产生仓库改动。
按照进程、服务器注册、账号授权、文件权限、节点链接、载荷大小逐层检查，每次只改变一个变量，才能确定故障真正来自哪里。
先选连接方式，再动配置
Figma 同时提供托管式远程端点和桌面端点，两者都能向 Claude Code 提供设计上下文，但运行前提不同。对多数团队来说，默认应使用 https://mcp.figma.com/mcp。桌面端点 http://127.0.0.1:3845/mcp 只在本机可用，还依赖 Figma 桌面应用、符合要求的席位以及当前画布状态。
| 方案 | 连接方式 | 适用情况 | 先检查 |
|---|---|---|---|
| 官方插件 | 通过一条 Claude Code 命令安装远程 MCP 配置及配套技能。 | 希望使用官方默认路径，并尽量减少手工配置。 | 插件是否安装、是否重启、浏览器授权是否完成。 |
| 手动远程连接 | 把 Figma 托管地址直接注册为 HTTP MCP 服务器。 | 环境统一管理 MCP 注册项，或无法使用插件。 | 端点是否准确、传输类型是否正确、OAuth 是否完成。 |
| 桌面服务器 | Claude Code 调用由 Figma 桌面应用开放的本机端点。 | 本地工作流或组织策略明确要求使用桌面模式。 | 桌面应用状态、席位资格、当前选区和本地端口。 |
在普通终端中运行 claude plugin install figma@claude-plugins-official。命令结束后彻底退出并重新打开 Claude Code，让新进程加载服务器注册信息。
在 MCP 或插件界面发起连接，并在浏览器中完成 Figma 授权。务必选择真正拥有目标文件访问权限的账号；误用另一个个人账号，是后续出现权限错误的常见原因。
运行 /mcp 并查看 Figma 条目。如果列表里根本没有 Figma，就应继续检查注册与进程加载，而不是反复授权；未加载的插件不会因为重新登录而出现。
在 Figma 中选中目标画框或组件并复制直达链接，让 Claude Code 返回节点名称、可见状态、设计变量和主要子元素。只提供文件首页链接通常缺少节点标识，不能作为可靠测试。
用四层测试确认连接真的可用
不要把一个状态图标当成端到端成功的证据。有效验证应从传输层开始，依次检查身份、设计读取以及语义质量，并在第一个失败点停下来。这样可以把问题范围压到最小，避免只得到“Figma 不能用”这种无法行动的结论。
| 层级 | 测试 | 通过证据 | 失败时 |
|---|---|---|---|
| 传输 | 在 /mcp 中查看 Figma。 | 服务器已列出并显示连接成功。 | 先重启，再检查插件或服务器注册。 |
| 身份 | 用授权账号打开目标文件。 | 文件及链接节点均可查看。 | 重新授权正确账号，或申请文件权限。 |
| 读取 | 请求一个小画框的元数据。 | Claude Code 返回正确节点及子元素。 | 重新复制节点直链，并缩小选区。 |
| 语义 | 核对组件、变量、状态与截图。 | 结构化信息与可见设计一致。 | 改善文件结构，或缩小请求范围。 |
可复用测试提示词：“读取这个 Figma 画框，但不要修改仓库。返回画框名称、尺寸、组件实例、文字样式、颜色变量、间距规律和可见交互状态；无法读取的内容请明确标出。”这段提示词能把“连接是否可靠”与“代码实现是否正确”分开验证。
按症状排查，不要无目的重装
大多数连接故障都能归到某一层。开始修改前，先记录准确症状、服务器模式、授权账号以及一个可复现的节点链接。团队成员使用不同 Figma 席位或 Claude Code 版本时，这份记录尤其重要。
| 症状 | 可能层级 | 依次检查 |
|---|---|---|
/mcp 中没有 Figma | 安装或进程加载 | 插件安装结果 → 完整重启 → 当前 Claude Code 环境 → 注册项。 |
| 已列出但未连接 | 授权或端点 | OAuth 完成状态 → 远程地址 → 代理或防火墙 → 过期会话。 |
| 已连接但无权访问 | Figma 身份与文件权限 | 授权邮箱 → 团队成员关系 → 文件共享设置 → 席位或套餐限制。 |
| 上下文错误或为空 | 链接与选区 | 节点直链 → 节点是否仍存在 → 页面是否正确 → 缩小画框。 |
| 响应很慢或内容截断 | 请求范围与载荷 | 单个画框 → 先取元数据 → 再取目标上下文 → 必要时才取截图。 |
| 桌面端 localhost 错误 | 本地服务器可用性 | Figma 桌面端运行状态 → MCP 是否启用 → 3845 端口 → 本机安全软件。 |
权限、限额与正式环境规范
- 使用能够读取目标文件的最低权限账号完成授权，不要为了绕过共享问题而把整个设计库开放给更多人。
- Figma 的可用能力与调用限额会受套餐和席位影响。如果同一配置只对部分同事有效，应先比较账号权益，再改动配置。
- 排错时使用小范围节点请求。一次读取整页不仅更慢、占用更多上下文，也会让人难以区分是连接问题还是载荷过大。
- 连接测试阶段不要让 Claude Code 修改仓库。先证明读取稳定，再审查实现计划并授权代码变更。
明确 Figma 边界后再接入 QVeris
目前 QVeris 在线目录中没有与 Figma 完全对应的 Tool 或 Provider 页面，因此这里不会为了放链接而虚构匹配项。Figma 原生设计上下文仍应由 Figma MCP 负责；当更大的智能体流程还需要其他 API 或实时数据时，可以先阅读 QVeris 文档 了解接入方式，再到 QVeris演练场 验证候选能力。
- 保持 Figma 连接职责单一且可独立测试，不要把无关的数据调用混入同一个服务器。
- 明确记录设计读取、仓库修改、外部 API 调用和人工审批分别由谁负责。
- 每项外部能力都应先独立验证，再与设计转代码流程组合。
Claude Code MCP Figma 常见问题
常规 Claude Code 工作流优先使用远程服务器。只有确实需要本地画布选区，或组织策略明确要求时，才选择桌面端点。
通常是当前 Claude Code 进程没有加载插件或注册项。先确认安装结果，彻底退出后重新打开，再检查 /mcp，不要一上来反复做 OAuth。
连接状态与文件权限是两回事。请确认完成授权的是哪个 Figma 账号，并验证该账号确实能打开目标文件和对应节点。
选中目标画框或组件后复制直达链接。带节点信息的 URL 比普通文件首页或项目链接更容易让 Claude Code 找到准确上下文。
选区可能过大、文件结构不清晰，或缺少可复用变量与组件。先读取元数据，再缩小画框，只请求下一步真正需要的上下文。
不能。连接成功只证明设计上下文可访问；准确实现还需要检查现有仓库、映射组件、核对响应式状态并进行视觉验证。
参考资料与下一步
Figma Claude Code 配置
Figma MCP 服务器指南
Figma MCP 工具与提示词
Figma MCP 访问权限与席位
Claude Code MCP 文档
QVeris 文档
QVeris演练场