1. 为什么 Figma MCP 在 Claude Code 里总连不上Claude Code 接入 Figma 设计稿这件事本质上是在解决一个很具体的痛点设计稿里的间距、色值、圆角、字体层级靠人肉截图再口述给模型信息损耗极大。MCPModel Context Protocol就是让 Claude Code 能直接读取 Figma 节点数据的通道。配好之后你可以让 Claude Code 直接读某个 Figma 链接的 frame把结构数据转成 React 或 Vue 组件而不是对着截图猜。但真正动手配的时候问题往往不在 Figma 本身而在两处一是 Claude Code 的 MCP 服务注册方式二是模型请求走哪条链路。很多人卡在local proxy failed或者401前者通常是本地 MCP 进程没起来或 stdio 通道断了后者多半是模型侧的鉴权信息没配对。这两个报错看起来都和 Figma 无关实际却是整条链路里最容易断的环节。这篇面向的是已经在用 Claude Code、想把 Figma 设计稿接进工作流的开发者。你需要准备一个能正常运行的 Claude Code 环境、一个 Figma 个人访问令牌Personal Access Token、以及一个稳定的模型接入端点。下面我会把 settings 配置、MCP 注册、验证读取、报错排查完整走一遍配置片段可以直接复制。先说清楚整体链路Claude Code 通过 MCP 协议调用 Figma 数据服务Figma 服务用你的 API Key 去 Figma 官方接口拉节点数据而 Claude Code 本身在生成代码时又要调用大模型。所以这里有两条独立的鉴权线——Figma 的 Key 管设计稿读取模型的 Key 管代码生成。401 报错经常是后者别一看到 401 就只盯着 Figma。我试过把这两条线混在一起排查结果绕了很久。分开看之后问题定位快很多。下面按顺序来。2. TaoToken 前置把模型接入端点先固定下来在配 Figma MCP 之前建议先把 Claude Code 的模型接入端点固定好否则后面 MCP 配通了生成代码时又报鉴权错误你会分不清是哪一层的问题。TaoToken 在这里的角色是提供统一的模型接入端点。Claude Code 支持通过环境变量指定 Base URL 和 API Key这样模型请求就走你配置的端点而不是默认地址。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。你需要先在控制台创建一个 API Key。进入控制台后新建密钥复制出来备用。这个 Key 就是 Claude Code 调用模型时用的凭证和 Figma 的 Token 是两回事别搞混。Claude Code 读取模型配置的方式主要是环境变量ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN或ANTHROPIC_API_KEY。你可以写在 shell 的 profile 里也可以放在项目的 settings 文件里。我倾向于放在项目级配置方便不同项目用不同 Key。这里有个关键点Claude Code 的 settings 文件路径。项目级是.claude/settings.json用户级是~/.claude/settings.json。MCP 服务的注册信息则通常在~/.claude.json或项目根的.mcp.json。这几个文件别写串了写串了就会出现「明明配了却不生效」的情况。模型 ID 这块Claude Code 默认会请求 Claude 系列模型。你在 TaoToken 控制台确认一下可用的模型标识填到配置里。如果模型 ID 写错表现是请求返回模型不存在或 404而不是 401这个区分很有用。把模型端点固定好之后可以先单独验证一次模型请求能不能通再往下配 Figma MCP。验证方式很简单启动 Claude Code 随便问一句能正常返回就说明模型链路是通的。这一步过了后面再出 401基本就能锁定是 Figma 侧或 MCP 侧的问题。3. 可复制配置settings 与 MCP 服务注册这一节是核心给出可以直接复制的配置片段。分三块模型接入的 settings、Figma MCP 的服务注册、以及环境变量。先看模型接入的 settings。项目级.claude/settings.json可以这样写{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的TaoToken密钥, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }注意ANTHROPIC_BASE_URL填的是 API 端点不要带多余路径。ANTHROPIC_MODEL换成你在控制台确认可用的模型 ID。这个文件不要提交到版本控制密钥泄露风险很高建议加进.gitignore。接着是 Figma MCP 的服务注册。Claude Code 支持用命令行添加也支持直接写配置文件。命令行方式claude mcp add --transport stdio figma-dev \ --env FIGMA_API_KEY你的FigmaToken \ -- npx -y figma-developer-mcp --stdio这条命令注册了一个叫figma-dev的 stdio 类型 MCP 服务通过npx拉起figma-developer-mcp进程并把 Figma Token 通过环境变量传进去。--后面的部分是实际执行的命令。如果你更喜欢写配置文件项目根目录的.mcp.json这样写{ mcpServers: { figma-dev: { command: npx, args: [-y, figma-developer-mcp, --stdio], env: { FIGMA_API_KEY: 你的FigmaToken } } } }这里figma-dev是自定义别名避免和官方 MCP 冲突。FIGMA_API_KEY去 Figma 账号设置里生成个人访问令牌权限至少要有读取文件内容的范围。三件套对照一下别缺项项目值作用Base URLhttps://taotoken.net/api模型请求端点API KeyTaoToken 控制台生成模型鉴权Model ID控制台确认的模型标识指定生成模型Figma TokenFigma 设置生成读取设计稿Figma Token 和 TaoToken 的 Key 是两个独立凭证分别管设计稿读取和模型生成。配置时把这两个都放对位置后面排查会省很多事。写完配置后重启 Claude Code让它重新加载 settings 和 MCP 注册信息。重启后在 Claude Code 里输入/mcp查看服务状态正常的话能看到figma-dev处于 connected 状态。如果显示 failed先看下一节的排查。4. 验证请求确认 Figma 设计数据能被正确读取配置写完不代表能用得实际验证一次 Figma 数据能不能被读出来。这一步很多人跳过结果生成代码时才发现读的是空数据。验证分两个动作。第一个动作是确认 MCP 服务已连接。在 Claude Code 里输入/mcp你会看到已注册的服务列表和状态。figma-dev应该是 connected。如果是 failed 或 disconnected先别往下走去第 5 节排查。第二个动作是实际调用一次 Figma 数据读取。准备一个 Figma 文件链接格式类似https://www.figma.com/file/xxxxx/项目名?node-id1-2。在 Claude Code 里发一条指令让它读取这个节点请用 figma-dev 读取这个 Figma 节点的结构数据 https://www.figma.com/file/xxxxx/项目名?node-id1-2 然后告诉我这个 frame 里有哪些子元素、它们的层级关系。如果配置正确Claude Code 会调用 MCP 工具返回该节点的 JSON 结构包含图层名称、类型、位置、尺寸等信息。你能看到类似FRAME、TEXT、RECTANGLE这样的节点类型以及嵌套关系。成功返回的标志有三个一是 MCP 工具被调用Claude Code 会显示工具调用记录二是返回内容里有真实的节点数据而不是报错三是数据里的节点名称和你 Figma 里的图层名对得上。如果返回的是空数据或者报「无法读取」检查 Figma Token 是否有该文件的访问权限。团队文件需要 Token 所属账号在团队里个人文件要确认链接没设成私有且 Token 有 read 权限。验证通过后你就可以让 Claude Code 基于这些结构数据生成组件代码了。比如让它把读到的 frame 转成 React 组件它会结合节点层级、间距、文字内容来生成比纯截图还原度高不少。5. 本篇常见错排查401、local proxy failed 与读取失败这一节把几个高频报错逐个拆开。这些报错我在配置过程中基本都遇到过按下面的顺序排查效率最高。401 报错。401 是鉴权失败但要先分清是哪一层的 401。如果报错信息里出现模型相关的字样比如invalid api key或authentication_error那是 TaoToken 的 Key 没配对检查ANTHROPIC_AUTH_TOKEN是否填了完整密钥、有没有多余空格。如果报错出现在调用 Figma 工具时那是 Figma Token 的问题检查 Token 是否过期、权限是否够。区分方法很简单看报错发生在模型生成阶段还是 MCP 工具调用阶段。local proxy failed。这个报错通常出现在 MCP 服务启动阶段意思是本地 MCP 进程没拉起来。常见原因有三个一是npx命令找不到检查 Node.js 是否安装、npx是否在 PATH 里二是figma-developer-mcp包下载失败网络问题导致npx -y拉不下来可以先手动npm install -g figma-developer-mcp再改配置用全局命令三是 stdio 通道参数写错确认--stdio参数在正确位置。reading choices 报错。这类报错一般和模型返回格式有关出现在模型响应解析阶段。检查ANTHROPIC_MODEL填的模型 ID 是否真实可用有些模型标识写错会导致返回结构不符合预期。另外确认 Base URL 没有多写或漏写路径。OAuth 相关报错。如果你用的是 Figma 官方 MCP首次连接需要 OAuth 授权。报错通常是授权没完成或 token 过期。开源版figma-developer-mcp用的是个人访问令牌不走 OAuth所以如果你看到 OAuth 报错说明你注册的是官方 MCP检查注册命令里的 URL 是不是https://mcp.figma.com/mcp。想换成开源版就删掉重新注册。MCP 显示 connected 但读取返回空。这种情况多半是 Figma 链接里的node-id格式不对或者 Token 没有该文件权限。Figma 链接里的 node-id 有时是1-2有时是1:2两种格式都试一下。权限问题就去 Figma 确认 Token 所属账号能打开该文件。排查时有个通用技巧把 MCP 服务和模型接入分开测。先用/mcp确认服务连接再单独发一条不涉及 Figma 的消息确认模型能返回最后再测 Figma 读取。这样能快速定位是哪一层断了。6. 把配置沉淀成可复用工作流配置跑通之后建议把几个关键动作固化成习惯避免每次换项目重踩一遍。第一把模型接入的 settings 做成模板。新建项目时直接复制.claude/settings.json只改模型 ID 和 Key。MCP 注册信息同理.mcp.json可以跨项目复用只要 Figma Token 不变。第二Figma Token 和 TaoToken Key 都用环境变量管理不要硬编码在会提交的文件里。可以在 shell profile 里 exportsettings 里用变量引用。这样密钥不会进版本库。第三验证动作标准化。每次新项目配好 MCP先跑一次/mcp加一次节点读取确认链路通了再开始生成代码。这个习惯能省掉大量「生成结果不对但不知道哪错了」的时间。第四模型接入端点固定用 https://taotoken.net/api 需要新建或轮换 Key 时去控制台操作。控制台地址是 https://taotoken.net/api-keys 接入文档在 https://taotoken.net/doc 。如果只是想先验证模型能不能正常对话可以用模型对话页面 https://taotoken.net/chat 快速试一次。长期做编码和 Agent 任务的话Coding Plan 页面 https://taotoken.net/coding-plan 有对应的方案说明。第五Figma 数据读取和代码生成之间建议加一步人工确认。让 Claude Code 先把读到的节点结构列出来你确认层级和内容对了再让它生成代码。这样即使数据读取有问题也能在生成前发现而不是生成一堆错代码再回头找原因。这套流程跑顺之后从 Figma 设计稿到组件代码的链路就基本自动化了。真正花时间的往往不是配置本身而是排查那几条鉴权线和进程启动问题。把第 5 节的排查顺序记住下次遇到报错能直接定位。