1. 为什么要把 Figma 画布接进 Codex/CC先说清楚一件事把 Figma 画布接入 Codex 或 Claude Code下称 CC本质上是让 AI 编程助手能看见你的设计稿然后基于设计稿直接生成代码、修改组件、对齐样式。这件事在 2024 年下半年开始变得可行核心原因是 MCP 协议Model Context Protocol的成熟——它给 AI 工具开了一个标准化的外挂接口让 AI 能调用外部服务读取数据。以前的工作流是什么样的设计师在 Figma 里画完稿前端工程师对着设计稿量间距、取色值、抄字号一个页面切图加还原少说半天。有了 Figma MCP 之后你可以直接对 Codex 说把这个 Frame 转成 React 组件它会通过 MCP 读取 Figma 的节点树、样式属性、布局约束然后生成对应的代码。这不是概念演示是已经能跑通的流程。但这里有个前提你得把整条链路搭起来。链路大概是这样的——Figma 桌面端或网页端开启 Dev Mode MCP Server本地跑一个 MCP 服务Codex/CC 通过配置文件连接到这个服务然后 AI 才能读取画布数据。任何一环出问题你看到的都是local proxy failed或者401 unauthorized这类报错。我写这篇东西的原因很简单网上关于 Figma MCP 的教程大多是碎片化的要么只讲 Figma 侧怎么开要么只讲 CC 侧怎么配中间那层为什么连不上没人讲透。我前后搭了三套环境macOS、Windows、以及一台 Linux 开发机踩了不少坑这里把完整链路和排查思路整理出来。适合谁看如果你是全栈或前端工程师想让 AI 帮你做设计稿还原如果你是独立开发者想用 Codex 快速把 Figma 原型变成可运行代码或者你只是好奇 MCP 到底怎么落地——这篇都能给你一条能走通的路。注意本文涉及的 Figma MCP、Codex、CC 均为正常开发工具所有操作在本地开发环境完成不涉及任何网络代理配置。2. Figma 侧的准备Dev Mode MCP Server 到底怎么开2.1 版本要求与入口位置Figma 的 MCP 功能藏在 Dev Mode 里不是所有版本都能看到。你需要满足两个条件一是 Figma 桌面客户端网页版部分功能受限二是账号有 Dev Mode 权限付费席位或团队版。我实测下来桌面端版本要在 124 以上Dev Mode MCP Server 的开关才会出现在设置里。打开路径是这样的启动 Figma 桌面端打开任意一个设计文件右上角切换到 Dev Mode快捷键Shift D然后在右侧面板顶部找到 MCP Server 的图标。如果找不到去Preferences里搜 MCP确认Enable Dev Mode MCP Server是打开状态。这里有个容易忽略的点MCP Server 是按文件开启的不是全局的。也就是说你在 A 文件里开了切到 B 文件可能又得重新开一次。我第一次配的时候以为是全局设置结果在另一个文件里怎么都连不上排查了半小时才发现是这个原因。2.2 本地服务端口与连接方式开启之后Figma 会在本地起一个 HTTP 服务默认监听127.0.0.1:3845。你可以用浏览器直接访问http://127.0.0.1:3845/sse看看有没有响应——如果返回一串 SSE 事件流说明服务是活的。这个端口是可以改的在 MCP Server 的设置面板里有个Port输入框。我建议如果你本地 3845 被占用了比如某些开发工具会占用这个段改成 3846 或 3850 都行但改完记得同步更新 Codex/CC 的配置否则就是经典的服务在跑但连不上。连接方式上Figma MCP 走的是 SSEServer-Sent Events传输不是标准的 stdio。这意味着你在配置 MCP 客户端时transport类型要选sseURL 填http://127.0.0.1:3845/sse。很多人配错就错在这里——用了 stdio 的配置模板结果一直报连接失败。2.3 Token 获取与权限范围关于 figma mcp token 在哪获取 这个问题实际情况是本地 Dev Mode MCP Server 不需要额外 Token。它依赖的是 Figma 客户端本身的登录态服务只在本地回环地址上监听不对外暴露。但如果你用的是 Figma 的 REST API 方式比如自己写脚本调/v1/files接口那就需要 Personal Access Token。获取路径是Figma 网页版 → 右上角头像 → Settings → Security → Personal Access Tokens → Generate new token。权限范围至少要勾File content和Dev resources读权限。这两种方式的区别很重要Dev Mode MCP Server 是给 AI 工具实时读取画布用的走本地 SSEREST API 是给脚本批量拉数据用的走 HTTPS Token。别把两者搞混否则你会一直在找为什么 MCP 配置里要填 Token——答案是不用填。提示如果你在团队环境里确认管理员没有禁用 Dev Mode MCP 功能。有些企业版策略会默认关闭这个开关表现就是设置里根本看不到 MCP 选项。3. Codex 与 CC 的 MCP 配置配置文件写对才是关键3.1 Codex 的 MCP 配置结构Codex 的 MCP 配置放在~/.codex/config.tomlmacOS/Linux或%USERPROFILE%\.codex\config.tomlWindows。一个能用的 Figma MCP 配置长这样[mcp_servers.figma] transport sse url http://127.0.0.1:3845/sse就这三行没有 Token没有额外参数。我第一次配的时候加了一堆command、args字段结果 Codex 启动直接报配置解析错误——因为 SSE 类型的 server 不需要 command那是 stdio 类型才有的字段。配完之后重启 Codex用/mcp命令或对应的查看命令确认 server 状态是connected。如果显示failed先别急着改配置去看 Figma 那边的服务是不是还开着——Figma 客户端一关MCP Server 就停了这是最常见的昨天还好好的今天就连不上的原因。3.2 CCClaude Code的配置差异CC 的 MCP 配置走的是claude_desktop_config.json或项目级的.mcp.json。结构上和 Codex 类似但字段名不同{ mcpServers: { figma: { type: sse, url: http://127.0.0.1:3845/sse } } }注意type字段CC 用的是type而不是transport。这个差异坑过我一次——我把 Codex 的配置直接复制到 CC 里结果 CC 完全不认因为它期望的是type。两个工具的配置 schema 不通用别偷懒复制。CC 还有个特性它支持项目级 MCP 配置。你可以在项目根目录放一个.mcp.json这样团队成员拉下代码就自带 MCP 配置不用每个人手动配。对于团队协作场景这个比全局配置实用得多。3.3 配置生效的验证方法配完不算完得验证。我的验证流程分三步第一步确认 Figma 服务活着。浏览器访问http://127.0.0.1:3845/sse能看到事件流就说明服务正常。第二步确认 AI 工具识别到了 server。Codex 里跑/mcp listCC 里跑/mcp看 figma 这个 server 在不在列表里状态是不是 connected。第三步实际调用一次。对 Codex 说读取当前 Figma 选中的 Frame列出它的子节点如果它能返回节点名称和层级说明整条链路通了。这三步里任何一步失败问题定位就很清晰了第一步失败是 Figma 侧问题第二步失败是配置问题第三步失败是权限或数据问题。4. 那些让人抓狂的报错逐条拆解与修复4.1 local proxy failed 系列报错cc switch local proxy failed while handling codex endpoint /responses这个报错字面意思是 CC 的本地代理在处理 Codex 的/responses端点时失败了。根因通常不是 Figma MCP 本身而是 CC 和 Codex 之间的模型路由配置有问题。我遇到这个报错时的场景是CC 配置了多个模型 provider其中一个 provider 的 endpoint 配错了导致 CC 的本地代理转发请求时找不到目标。修复方法是检查 CC 的 provider 配置确认每个 provider 的base_url和api_key都是有效的。如果报错里带了upstream_status: http 400和reasoning_content in the thinking mode must be passed back那是模型侧的问题——某些推理模型要求把 thinking 内容回传但客户端没传。这个和 Figma MCP 无关是模型调用层的事需要检查你用的模型是否支持当前客户端的调用方式。4.2 401 unauthorized 的排查路径unexpected status 401 unauthorized出现在 MCP 场景下通常意味着认证失败。但前面说了本地 Figma MCP 不需要 Token那 401 从哪来两种可能一是你连的根本不是本地 MCP而是某个需要认证的远程服务二是你的 AI 工具本身没登录或登录态过期。我遇到过一次是 CC 的账号登录过期了但它报的是 MCP 相关的 401误导了我半天。后来重新登录 CC 就好了。排查顺序建议先确认 AI 工具本身登录正常能正常对话再确认 MCP URL 指向的是127.0.0.1而不是某个远程地址最后检查 Figma 客户端是不是登录状态。4.3 404 not found 与端口占用unexpected status 404 not found: cc switch local proxy failed这个组合报错八成是端口对不上。Figma MCP Server 实际监听的端口和你配置里写的端口不一致请求打到了错误的端口上自然 404。怎么确认实际端口在 Figma 的 MCP Server 设置面板里看Port字段的值或者用lsof -i :3845macOS/Linux/netstat -ano | findstr 3845Windows看端口占用情况。如果 3845 被别的进程占了Figma 可能会自动换端口但配置里还是旧的就对不上了。我的做法是固定端口在 Figma 设置里手动指定一个不常用的端口比如 3855然后配置里写死这个值避免自动分配带来的不确定性。4.4 Windows 上的虚拟化平台报错claudes workspace requires the virtual machine platform on windows这个报错和 MCP 没直接关系是 CC 在 Windows 上需要虚拟化平台支持。开启方法控制面板 → 程序和功能 → 启用或关闭 Windows 功能 → 勾选虚拟机平台和Windows Subsystem for Linux重启后生效。这个坑的隐蔽性在于它报错的时候你可能正在配 MCP会误以为是 MCP 配置问题。实际上 CC 的某些功能依赖 WSL2没开虚拟化平台就跑不起来。先把这个基础环境搞定再谈 MCP。5. 从画布到代码实际使用中的技巧与边界5.1 什么样的 Frame 适合直接转代码不是所有 Figma 设计稿都适合丢给 AI 转代码。我实测下来适合的 Frame 有几个特征用了 Auto Layout、命名规范不是Frame 123这种、组件化程度高、没有复杂的矢量插画。Auto Layout 是关键。因为 AI 读取的是布局约束信息如果设计稿是绝对定位堆出来的AI 生成的代码也会是一堆position: absolute维护性极差。而 Auto Layout 对应到代码里就是 flex 布局生成质量高很多。命名规范也很重要。一个叫Button/Primary/Default的组件AI 能直接生成PrimaryButton组件一个叫Rectangle 47的图层AI 只能瞎猜。花十分钟整理命名能省后面一小时的返工。5.2 提示词怎么写才能拿到可用的代码直接说把这个 Frame 转成代码效果一般。我的提示词模板是这样的读取 Figma 当前选中的 Frame分析它的布局结构Auto Layout 方向、间距、对齐方式 然后生成一个 React Tailwind 的组件。要求 1. 用语义化的组件名基于 Frame 的命名 2. 间距用 Tailwind 的 spacing scale不要写死 px 3. 颜色提取成 CSS 变量 4. 响应式断点参考 Frame 的约束设置这样 AI 拿到的指令是结构化的生成结果可用度高很多。关键是第 2 点——让它用 spacing scale 而不是写死 px这样生成的代码和设计系统能对齐。5.3 MCP 读取的数据边界Figma MCP 能读到什么、读不到什么这个边界得清楚。它能读节点树、布局属性、样式颜色、字体、圆角、阴影、组件实例关系、文本内容。它读不到交互原型逻辑、动效参数、设计意图为什么这么设计。所以别指望 AI 能理解这个按钮点击后要跳转到详情页——那是交互逻辑不在画布数据里。你得在提示词里补充这些信息。MCP 解决的是长什么样的问题不是怎么动的问题。另外复杂组件比如带嵌套实例的 Design System 组件读取时可能会有层级丢失。我的经验是如果组件嵌套超过三层先在设计稿里 flatten 一下或者分块读取别一次性丢给 AI。6. 多工具协同Codex、CC、Trae 的 MCP 复用思路6.1 一套 Figma 服务多个客户端共用Figma MCP Server 是本地 HTTP 服务这意味着它可以同时被多个客户端连接。你可以在 Codex 里配一份在 CC 里配一份在 Trae 里再配一份它们连的都是同一个http://127.0.0.1:3845/sse互不干扰。这个特性很实用比如你用 Codex 做代码生成用 CC 做代码审查两个工具都能读同一份设计稿数据不用来回切换 Figma 文件。我现在的习惯是 Codex 负责从设计稿生成初版代码CC 负责对照设计稿检查还原度形成一个小闭环。6.2 配置文件的统一管理多工具配置的痛点是Figma 端口一改三个配置文件都得改。我的做法是写一个简单的同步脚本把端口值抽成一个环境变量配置生成时动态替换。#!/bin/bash FIGMA_MCP_PORT${FIGMA_MCP_PORT:-3845} # 生成 Codex 配置 cat ~/.codex/config.toml EOF [mcp_servers.figma] transport sse url http://127.0.0.1:${FIGMA_MCP_PORT}/sse EOF # 生成 CC 配置 cat ~/.claude/claude_desktop_config.json EOF { mcpServers: { figma: { type: sse, url: http://127.0.0.1:${FIGMA_MCP_PORT}/sse } } } EOF这样改端口只需要改一个环境变量重跑脚本就行。虽然简单但省去了每次手动改三个文件的麻烦。6.3 什么时候该用 MCP什么时候该用截图MCP 不是万能的。有些场景下直接截图丢给 AI 反而更快比如设计稿里有大量自定义插画、渐变、复杂阴影MCP 读取的样式数据 AI 未必能准确还原不如截图让它看着办。我的判断标准是如果设计稿是标准组件拼的用 MCP如果设计稿有大量视觉创意元素用截图 文字描述。MCP 的优势在于精确读取布局和样式数值截图的优势在于 AI 能理解整体视觉意图。两者结合用效果最好。7. 我踩过的几个真实坑与最终稳定方案第一个坑是 Figma 客户端更新后 MCP 开关重置。有一次 Figma 自动更新到新版本我打开文件发现 MCP Server 又关了配置没动但就是连不上。后来养成习惯每次 Figma 更新后第一件事是检查 MCP Server 开关状态。第二个坑是端口冲突导致的间歇性失败。我本地有个开发服务偶尔会占用 3845导致 Figma MCP 时好时坏。表现是有时候能连有时候不能特别难排查。后来固定用 3855 端口再没出现过这个问题。第三个坑是 CC 和 Codex 同时连接时的资源竞争。两个客户端同时高频读取 Figma 数据时偶尔会出现响应超时。我的解决方案是错开使用——生成代码时用 Codex审查时用 CC不同时跑。最终我的稳定方案是Figma 桌面端固定开 MCP Server 在 3855 端口Codex 和 CC 各配一份 SSE 连接用一个同步脚本管理配置。日常使用中Codex 负责生成CC 负责审查Figma 画布保持打开状态。这套方案跑了两个月除了 Figma 更新时需要重新开一下开关没再出过其他问题。如果你刚开始搭我的建议是先用最简配置跑通一条链路Figma Codex确认能读取数据了再往上加 CC 或其他工具。一次性配一堆出问题的时候根本不知道是哪一环的锅。