1. 从 Penpot 到 ClaudeAI 原型设计链路里最容易被卡住的一环Claude 连接 Penpot MCP server 做 AI 原型设计本质上是让 Claude 这类支持 MCP 协议的客户端通过一个标准化的 server 端点去读写你 Penpot 里当前打开的设计文件。它能做什么简单说你可以用自然语言让 Claude 在 Penpot 里创建页面、生成组件、批量重命名图层、导出画板甚至根据一份需求文档直接铺出一整套高保真原型。适合谁适合那些不想在 Figma 和代码之间来回倒腾、希望把需求→原型→前端代码串成一条流水线的人尤其是对前端不熟但想快速出可运行系统的开发者。但这条链路里真正让人卡住的往往不是 Penpot 本身而是 MCP endpoint 和鉴权配置。Penpot 官方给的 MCP server 地址是https://your-penpot-domain/mcp/stream?userTokenYOUR_MCP_KEY这种形式本地模式则是http://localhost:4401/mcp。问题在于很多人在 Claude Code 里直接把这个 URL 塞进mcpServers配置结果claude mcp list一看penpot 那行显示✗ Failed to connect。我试过好几次报错五花八门有的是 transport 类型没写对有的是mcp-remote没加--allow-http还有的是 key 过期了但配置里还留着旧的。这篇要解决的核心就是把 MCP endpoint 正确指向你的 Penpot MCP server同时把鉴权MCP key 或本地会话配好让 Claude 能稳定连上然后跑一次只读验证再跑一次原型生成测试。如果你希望把这条链路里的模型调用统一走一个 Key 通道也可以把 endpoint 指向 TaoToken 的统一 API 通道后面会给可复制的配置片段。先说清楚 Penpot MCP 的架构不然后面配 endpoint 会懵。它由三部分组成MCP server暴露工具给 AI 客户端、Penpot 内的 MCP plugin运行在 Penpot 里把你当前聚焦的文件连到 server、MCP client你输入提示词的地方比如 Claude Code。关键点是MCP 永远作用于你在 Penpot 中聚焦的那个页面切换聚焦页面MCP 上下文跟着走而且同一时间只能在一个浏览器标签页里激活。这意味着你配置 endpoint 之前必须先在 Penpot 里打开一个文件并通过 File → MCP Server → Connect 把插件连上否则 Claude 那边连上了也找不到操作目标。远程模式和本地模式的 endpoint 写法完全不同。远程模式是官方托管URL 里内嵌了userToken你的MCP key认证靠这个 key本地模式跑在你自己机器上用npx penpot/mcpstable启动endpoint 是http://localhost:4401/mcp不需要 key认证靠当前激活的 Penpot 浏览器会话。两种模式在 Claude Code 里的配置写法也不一样这是最容易出错的地方。下面我会分别给出可复制的配置并说明每种写法对应的报错特征。2. TaoToken 前置把 MCP endpoint 与模型调用通道统一起来在讲具体配置之前先说一下为什么要把 endpoint 指向 TaoToken 的统一通道。Penpot MCP server 本身只负责设计文件的读写它不负责模型推理。真正做原型设计的是 Claude 这个模型而 Claude 的调用需要 API 通道。如果你在 Claude Code 里同时配了 Penpot MCP server 和模型 API两套鉴权、两个 endpoint管理起来很乱。把模型调用统一走 TaoToken 的 API 通道可以让你的 Key 管理集中在一处MCP server 的 endpoint 和模型 API 的 Base URL 分开配置互不干扰。TaoToken 的官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。注意 API 地址不加 UTM 参数直接用它作为 Base URL。你需要先在控制台创建一个 API Key这个 Key 用于模型调用Penpot 那边的 MCP key 是另一套别混了。具体来说Claude Code 的模型调用配置和 MCP server 配置是分开的两个文件。模型调用走环境变量或 settings 文件MCP server 走.mcp.json。我建议这样分工模型 API 的 Base URL 指向https://taotoken.net/apiKey 用 TaoToken 控制台生成的Penpot MCP server 的 endpoint 指向你的 Penpot MCP 地址远程或本地。这样 Claude 负责推理Penpot MCP server 负责设计文件操作各司其职。如果你用的是 Claude Code 的 coding-plan 模式可以在控制台里选对应的套餐然后拿到 Key。模型对话可以在 https://taotoken.net/models 这里试确认 Key 能用、模型能返回结果再去配 MCP。这一步别跳过因为如果模型通道本身不通MCP 配得再对也没用——Claude 连上了 Penpot但推理请求发不出去表现就是连上了但不动。关于模型选择Penpot MCP 的官方建议是用 frontier 模型任务越复杂对模型质量影响越大。理解图片必须用视觉语言模型VLM大多数商用 LLM 都是。如果你要做的是从设计稿生成代码这类任务模型能力直接决定输出质量。TaoToken 的模型列表里可以选支持视觉的模型具体在模型对话页面能看到可用列表。还有一点Penpot MCP 的写操作是有风险的。连接后AI 客户端可以执行修改当前聚焦页面的操作——创建、重命名、移动、删除、改样式。所以配置好之后第一件事是跑只读提示词验证别一上来就让它改文件。我踩过的坑就是一开始就让 Claude 帮我整理一下这个文件的结构结果它把几个图层重命名了虽然可逆但当时没心理准备。建议的节奏是先只读列出页面、分析结构、列出颜色样式再轻量写创建一套 color token最后才是大范围操作。3. 可复制配置Claude Code 连接 Penpot MCP server 的完整写法这一节给可直接复制的配置片段。分两部分模型调用通道指向 TaoToken和 Penpot MCP server指向你的 Penpot 地址。先看模型调用。Claude Code 的模型配置可以通过环境变量或 settings 文件。如果你用 settings 文件路径通常在~/.claude/settings.json或项目级的.claude/settings.json。写入以下内容{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: 你的TaoToken_API_Key } }注意ANTHROPIC_BASE_URL后面不要加/v1TaoToken 的 API 入口就是https://taotoken.net/api。Key 从控制台生成格式通常是一串以sk-开头的字符串。配好后可以用claude命令进交互模式随便问一句确认模型能返回。再看 Penpot MCP server 的配置。这是重点也是最容易配错的地方。在项目根目录创建.mcp.json或者用claude mcp add命令添加。先给远程模式的正确写法{ mcpServers: { penpot: { command: npx, args: [ -y, mcp-remote, https://design.penpot.app/mcp/stream?userToken你的MCP_KEY, --allow-http ] } } }这里有几个关键点。第一远程模式的 URL 里内嵌了userToken这个 key 从 Penpot 的 Your account → Integrations → MCP Server 页面生成只显示一次务必保存。第二用mcp-remote这个包来桥接而不是直接把 URL 写成url: ...。很多人配错就是因为直接写了url字段Claude Code 对 HTTP transport 的支持在不同版本里表现不一样用mcp-remote更稳。第三--allow-http这个参数在本地模式http://localhost时必须加远程 https 模式其实可以不加但加上不影响。本地模式的写法{ mcpServers: { penpot: { command: npx, args: [ -y, mcp-remote, http://localhost:4401/mcp, --allow-http ] } } }本地模式不需要userToken认证靠当前激活的 Penpot 浏览器会话。但前提是你已经用npx penpot/mcpstable启动了本地 server并且在 Penpot 里通过 Plugins → Load from URL 加载了http://localhost:4400/manifest.json然后运行插件点了 Connect to MCP server。如果你用的是 Cursor配置字段名不一样是mcpServerstype: httpVS Code/Copilot 用mcp.serverstransport: httpCodex/OpenCode 用serverstransport.type: http。Claude Code 用上面给的commandargs写法最稳。配好之后用claude mcp list检查连接状态。正常应该看到类似penpot: npx -y mcp-remote https://design.penpot.app/mcp/stream?userToken... --allow-http - ✓ Connected如果显示✗ Failed to connect先别急着改配置往下看第 5 节的排查。还有一个细节Penpot MCP 的 key 是个人、不可恢复的令牌每个用户同一时间只能有一个 key远程模式。如果你重新生成了 key旧 key 立即失效所有用旧 key 的客户端都会停止工作需要更新配置。key 过期也会导致连接失败。所以如果你之前配过、后来连不上第一件事是去 Integrations 页面确认 key 是否还有效。4. 验证请求与原型生成测试从只读确认到出稿配置写完先别急着做原型。第一步是验证连接用只读提示词确认工具已列出、文件能读到。在 Claude Code 里输入请通过 execute_code 获取当前 Penpot 文件的名称和 ID确认连接正常。如果返回了文件名和 ID说明 MCP 通道通了。这一步对应的是 Penpot MCP 暴露的execute_code工具它能在 Penpot 插件上下文里执行 JavaScript。Penpot MCP 当前暴露 5 个工具execute_code、high_level_overview、penpot_api_info、export_shape、import_image。其中high_level_overview是必须先读的它给的是 Penpot 工具使用总览penpot_api_info用来查 Penpot API 的类型和成员文档。只读验证通过后再跑一个稍微复杂点的只读提示词确认它能理解文件结构列出当前 Penpot 文件里的所有页面并分析这个设计的结构总结一下有哪些主要模块。这一步能返回页面列表和结构分析说明 Claude 已经能读取文件内容了。注意Penpot MCP 永远作用于你当前聚焦的页面所以如果你在 Penpot 里切换了页面Claude 读到的内容也会跟着变。接下来是原型生成测试。这里给一个可复制的提示词用于从需求文档生成原型请读取项目 openspec/specs/ 下的所有 spec.md 文件解析其中的 Requirements 和 GIVEN/WHEN/THEN Scenarios推断出所有需要的前端页面和交互流程。然后在当前 Penpot 文件中 1. 创建一套完整的设计系统颜色、字体、组件 2. 按推断出的页面清单逐个创建高保真原型页面 3. 根据 Scenarios 中的用户操作流程添加页面跳转交互 要求所有文本中文桌面端 1440×900每个 Scenario 的初始状态、用户操作、系统反馈都要在原型中体现。这个提示词的关键是先解析 spec再推断页面再创建。如果你直接说帮我设计一个系统Claude 没有依据出来的东西会很泛。给它 spec 文件作为需求真值它就能按 Scenario 逐个铺页面。执行过程中你会在 Penpot 界面上看到自动设计的过程——不断有新页面和画板被创建出来。这个过程可能比较长取决于页面数量。我实测下来10 个页面、27 个画板、141 个交互大概跑了 50 分钟左右。中途如果输出上下文超限会报API Error: Claudes response exceeded the 8192 output token maximum这时候需要分批执行或者设置CLAUDE_CODE_MAX_OUTPUT_TOKENS环境变量调大上限。生成完成后Claude 会汇报完成情况包括创建了多少页面、多少画板、设计系统包含哪些 token、交互跳转有多少条。你可以打开 Penpot 的原型模式Prototype点击验证跳转是否生效。如果要做导出比如把设计资产拉到本地 Git 仓库可以用这样的提示词请通过 Penpot MCP 完成以下批量导出任务 1. 导出当前文件的所有 Design Tokens 为 JSON保存到本地 penpot-assets/tokens/design-tokens.json 2. 导出所有页面的画板为 PNG1x 和 2x保存到 penpot-assets/exports/pages/ 3. 导出所有组件为 SVG保存到 penpot-assets/exports/components/ 4. 读取当前文件结构生成一份《设计资产清单》Markdown 文档 请分批执行每批不超过 10 个操作。注意远程 MCP 不暴露本地文件系统访问import_image的本地路径不可用export_shape可用但受限不能直接导出到本地文件路径。所以导出到本地需要走本地接收服务或者本地模式。如果你用的是远程模式导出功能会受限这是正常的。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth这一节对照真实报错给排查路径。这些是我在实际配置过程中遇到过的按出现频率排序。报错一✗ Failed to connectclaude mcp list里 penpot 那行显示失败。最常见的原因是配置写法不对。如果你直接写了url: http://localhost:9001/mcp/stream?userToken...而没有用mcp-remote桥接Claude Code 可能无法正确识别 HTTP transport。正确的写法是用command: npxargs: [-y, mcp-remote, URL, --allow-http]。另外本地模式必须加--allow-http否则mcp-remote会拒绝连接 http 地址。报错二401 Unauthorized或userToken无效。这说明 MCP key 有问题。可能的原因key 过期了、key 被重新生成过旧 key 立即失效、或者 URL 里的userToken拼写有误。去 Penpot 的 Your account → Integrations → MCP Server 页面确认 key 状态必要时重新生成。注意 key 只显示一次重新生成后要立即更新配置。报错三local proxy failed或连接被拒绝。这个通常出现在本地模式。检查三件事第一npx penpot/mcpstable是否还在运行那个终端不能关第二Penpot 里的插件是否显示 Connected插件窗口要保持打开第三浏览器是否拦截了https://design.penpot.app到http://localhost的连接。部分 Chromium 系浏览器会拦截遇到时显式允许本地网络访问或者改用 Firefox。报错四reading choices或类似 undefined 报错。这个报错通常不是 MCP 本身的问题而是模型 API 返回格式不对。检查你的ANTHROPIC_BASE_URL是否指向了正确的 API 入口Key 是否有效。如果 Base URL 写成了https://taotoken.net/api/v1这种带/v1的形式可能会导致路径拼接错误。TaoToken 的 API 入口就是https://taotoken.net/api不要加/v1。另外确认模型名称是否正确模型列表在模型对话页面可以查。报错五OAuth 相关报错或者提示需要登录。Claude Code 在某些版本里会尝试 OAuth 流程。如果你用的是 API Key 模式确保ANTHROPIC_API_KEY环境变量已设置并且没有残留的 OAuth 配置。检查~/.claude/目录下是否有冲突的配置文件。如果同时配了 OAuth 和 API Key可能会冲突。报错六API Error: Claudes response exceeded the 8192 output token maximum。这是输出 token 超限不是连接问题。解决办法是分批执行把大任务拆成小任务。比如导出 SVG 时不要一次导出所有组件先获取元素列表确认分组规则再按组批量导出每批不超过 3 个。或者设置CLAUDE_CODE_MAX_OUTPUT_TOKENS环境变量调大上限。报错七连接成功但 Claude 不动或者提示找不到文件。这通常是 Penpot 那边的问题。检查Penpot 里是否打开了文件、插件是否 Connect 了、当前聚焦页面是否正确。MCP 永远作用于当前聚焦的页面如果你在 Penpot 里没打开任何文件或者插件没连上Claude 就没有操作目标。另外Active MCP tab 同一时间只能有一个多开 Penpot 时要明确哪个标签拥有 MCP。排查顺序建议先重启 MCP server 进程再在 Penpot 中重启插件连接再重启 MCP 客户端或触发重连最后确认使用期间 Penpot 插件窗口保持打开。这个顺序能解决大部分临时性连接问题。6. 把这条链路用起来从原型到前端代码的完整路径配置跑通之后这条链路的真正价值在于把需求→原型→代码串起来。我实际走了一遍用 openspec 的 spec 文件驱动 Penpot 生成原型再用 Claude Code 连接 Penpot MCP 把设计资产导出到本地 Git 仓库最后用这些资产加 spec 生成一个可运行的 Vue3 前端系统。具体来说导出的资产分三类tokens/design-tokens.json是设计真值包含色值、字体、间距、圆角、阴影用于生成 CSS 变量exports/pages/*.png是视觉验收基准开发时逐像素比对exports/components/*.svg是组件规格书SVG 源码可读能直接看到精确色值、圆角、字号、坐标。这三类资产加上 spec 文件就是 Claude Code 生成前端代码的全部输入。生成前端代码时建议先写一份CLAUDE.md作为实验宪法锁定技术栈比如 Vue3 CSS 变量禁 Tailwind、指定设计真值路径、规定颜色只能用 token 变量、组件必须来自 ui/ 目录。然后按模块逐个生成一个会话做一个模块做完验收再下一个。每个模块的提示词模板是视图规格参照对应的 PNG行为规格以 spec 的全部 Scenario 为准API 端点见 spec 中的路径样式只用 tokens 变量和 ui 组件完成后 build 和 test 必须通过。这套流程跑下来一个可运行的 Web 系统就出来了。对于以前不做前端开发的人来说做一点要求不高的 Web 管理系统现在确实不用求人了。但要注意这条链路目前还有短板交互数据页面跳转关系在导出时容易遗漏需要单独补一份交互清单远程模式的导出功能受限需要本地模式或本地接收服务大任务容易触发 token 超限必须分批。如果你想把模型调用统一管理可以在控制台创建 Key把ANTHROPIC_BASE_URL指向https://taotoken.net/api。需要长期做编码和 Agent 任务的可以看看 coding-plan 模式。模型对话可以在 https://taotoken.net/models 试接入文档在 https://taotoken.net/doc 有详细说明。API Key 管理在 https://taotoken.net/api-keys 。Claude Code 相关的接入配置可以参考 https://taotoken.net/claude-code 。最后给一个实用技巧每次改完 MCP 配置先用claude mcp list确认连接状态再跑只读提示词验证最后才做写操作。这个顺序能帮你快速定位问题出在配置层、连接层还是操作层。另外Penpot 的 MCP key 当密码用不要出现在截图、日志或代码示例里疑似泄露立即重新生成。