1. Penpot 的 MCP Server 到底解决什么问题Penpot 是一个用 MPL 2.0 协议开源的在线设计工具GitHub 上已经积累了 47000 多颗 Star。它和 Figma 最大的区别在于两点一是可以自己用 Docker 部署设计文件完全落在自己的服务器上二是所有设计数据基于 SVG、CSS、HTML、JSON 这类开放标准存储不存在私有格式锁定。对于金融、医疗、政务这类对数据存放位置有硬性要求的团队来说这两点基本决定了选型结果。但真正让 Penpot 在开发者圈子里被反复讨论的是它内置的 MCP Server。MCP 是 Model Context Protocol 的缩写你可以把它理解成一套让 AI 模型和外部工具之间说同一种语言的协议。Penpot 把设计文件的结构、图层层级、组件关系、Design Tokens 这些信息通过 MCP Server 暴露出来AI 就能直接读取和操作设计数据而不是靠截图去猜。这意味着什么你画好一个界面AI 可以通过 MCP 协议拿到这个设计的完整结构哪个是容器、哪个是按钮、间距是多少、用了哪个 Token。然后它可以给出代码建议、做设计规范检查、甚至把设计迁移到另一个平台。这不是演示性质的接口是可以接进实际工作流的。我试过把 Penpot 的 MCP Server 接到自己的 AI 编码流程里整体感受是设计数据终于不再是黑盒了。以前开发拿到设计稿要手动量间距、猜字号、对颜色现在这些参数可以直接被程序读取。对于想把 AI 能力接入设计流程的开发者来说Penpot 的 MCP Server 是目前开源方案里比较少见的、能实际跑通的路径。这篇文章会从零开始带你完成三件事配置 Penpot 的 MCP Server、用 TaoToken 统一 Key 接入 AI 模型、用一次真实请求验证设计数据读写是否生效。每一步都有可复制的配置片段和命令跟着做就能跑起来。2. TaoToken 统一 Key 的前置准备与 MCP Server 环境搭建在开始配置之前先把两件事理清楚Penpot 的 MCP Server 怎么跑起来以及 TaoToken 在这里扮演什么角色。Penpot 的 MCP Server 本质上是一个独立的服务进程它通过 Penpot 的开放 API 读取设计文件数据然后以 MCP 协议的形式暴露给 AI 客户端。所以你需要先有一个能访问的 Penpot 实例。如果你已经在用自部署的 Penpot直接拿它的地址就行如果还没有官方提供了 Docker Compose 配置小团队用一台 4 核 8G 的机器就能跑起来。TaoToken 在这里的作用是统一管理 AI 模型的访问凭证。你不需要为每个模型单独申请 Key、单独配置环境变量而是用 TaoToken 的一个 Key 就能调用多个模型。它的 API 地址是https://taotoken.net/api兼容 OpenAI 的接口格式所以任何支持自定义 Base URL 的 AI 客户端都能接。具体操作步骤第一步注册并获取 TaoToken 的 API Key。打开https://taotoken.net/api-keys登录后创建一个新的 Key复制保存。这个 Key 后面会用在 MCP Server 的配置里。第二步确认你的 Penpot 实例地址。假设你的 Penpot 部署在http://localhost:9001那么它的 API 地址就是http://localhost:9001/api。如果你用的是 Penpot 官方云服务地址会不同以你实际使用的为准。第三步准备 MCP Server 的运行环境。Penpot 的 MCP Server 通常以 Node.js 包的形式提供你需要本地有 Node.js 18 以上的版本。可以用node -v检查如果版本不够去 Node.js 官网下载安装。第四步安装 MCP Server。打开终端执行npm install -g penpot/mcp-server安装完成后用penpot-mcp --version确认是否成功。如果提示命令找不到检查 npm 的全局 bin 目录是否在 PATH 里。到这里前置准备就完成了。你手里应该有一个 TaoToken 的 API Key、一个可访问的 Penpot 实例地址、一个装好的 MCP Server。接下来进入配置环节。注意TaoToken 的 API Key 不要直接写在代码里提交到 Git建议用环境变量或者单独的配置文件管理。后面我会给出具体的配置方式。3. 可复制的 MCP Server 配置片段与 TaoToken 接入这一节是核心操作部分。我会给出完整的配置文件片段你直接复制修改就能用。Penpot 的 MCP Server 支持通过配置文件或者环境变量来指定参数。推荐用配置文件的方式因为参数比较多写在文件里更清晰。在项目根目录创建一个penpot-mcp.config.json文件内容如下{ penpot: { baseUrl: http://localhost:9001, apiPath: /api, accessToken: 你的_Penpot_访问令牌 }, mcp: { serverName: penpot-design-server, version: 1.0.0, transport: stdio }, ai: { provider: taotoken, baseUrl: https://taotoken.net/api, apiKey: 你的_TaoToken_API_Key, modelId: gpt-4o } }这里有几个关键字段需要说明。penpot.baseUrl是你的 Penpot 实例地址penpot.accessToken是 Penpot 的访问令牌你可以在 Penpot 的个人设置里生成。ai.baseUrl固定填https://taotoken.net/apiai.apiKey填你在 TaoToken 控制台创建的 Keyai.modelId填你想用的模型 ID比如gpt-4o、claude-3-5-sonnet等具体支持哪些模型可以在 TaoToken 的模型列表页查看。如果你更习惯用环境变量的方式对应的配置是export PENPOT_BASE_URLhttp://localhost:9001 export PENPOT_ACCESS_TOKEN你的_Penpot_访问令牌 export TAOTOKEN_API_KEY你的_TaoToken_API_Key export TAOTOKEN_BASE_URLhttps://taotoken.net/api export TAOTOKEN_MODEL_IDgpt-4o然后在启动 MCP Server 时指定配置文件路径penpot-mcp --config ./penpot-mcp.config.json如果你用的是 Claude Code 或者 Cline 这类支持 MCP 的客户端需要在客户端的 MCP 配置里注册这个 Server。以 Claude Code 为例在~/.claude/claude_desktop_config.json里添加{ mcpServers: { penpot: { command: penpot-mcp, args: [--config, /绝对路径/penpot-mcp.config.json] } } }这里的三件套要写全Base URL 是https://taotoken.net/apiKey 是你的 TaoToken API KeyModel ID 是你要用的模型。这三个参数缺一不可否则请求会失败。配置完成后启动 MCP Server观察终端输出。如果看到类似MCP server running on stdio和Connected to Penpot at http://localhost:9001的日志说明服务已经正常启动。提示如果你的 Penpot 实例开启了 HTTPS 且用了自签名证书可能需要在配置里加上rejectUnauthorized: false但生产环境不建议这么做正确做法是把证书加到信任列表里。4. 验证请求用一次真实调用确认设计数据读写生效配置写好了服务也启动了但怎么确认它真的能工作这一节用一个具体的请求来验证。MCP 协议的核心是工具调用。Penpot 的 MCP Server 会暴露几个工具比如get_design_structure、get_design_tokens、update_design_token等。我们可以通过 AI 客户端发起一次调用让 AI 读取某个设计文件的结构然后返回结果。假设你在 Penpot 里有一个项目项目 ID 是abc123里面有一个页面叫Homepage。在 Claude Code 或者任何支持 MCP 的客户端里输入这样的指令请用 penpot 工具读取项目 abc123 中 Homepage 页面的设计结构列出所有顶层图层和它们的类型。如果一切正常AI 会调用 MCP Server 的get_design_structure工具Penpot 返回数据AI 整理后输出类似这样的结果Homepage 页面包含以下顶层图层 1. Header (Frame) - 包含 Logo、导航菜单、登录按钮 2. Hero Section (Frame) - 包含标题、副标题、CTA 按钮 3. Features Grid (Frame) - 包含 6 个 Feature Card 4. Footer (Frame) - 包含版权信息、社交链接看到这个输出说明设计数据的读取链路已经打通了。AI 通过 TaoToken 的 Key 调用模型模型通过 MCP 协议向 Penpot MCP Server 请求数据Server 再从 Penpot API 拿到结果返回。整条链路是通的。接下来验证写入。让 AI 修改一个 Design Token 的值请用 penpot 工具把项目 abc123 中名为 primary-color 的 Design Token 值改为 #1A73E8。如果成功你会看到 AI 返回确认信息同时去 Penpot 界面里刷新对应的 Token 值应该已经变了。这一步验证的是 MCP Server 的写入能力说明它不只是只读接口而是可以双向操作设计数据。如果你想用命令行直接测试不经过 AI 客户端可以用 curl 模拟 MCP 请求curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer 你的_TaoToken_API_Key \ -H Content-Type: application/json \ -d { model: gpt-4o, messages: [ {role: user, content: 读取 Penpot 项目 abc123 的设计结构} ], tools: [ { type: function, function: { name: get_design_structure, description: 获取 Penpot 项目的设计结构, parameters: { type: object, properties: { projectId: {type: string} }, required: [projectId] } } } ] }这个请求会返回模型对工具调用的响应。如果返回的 JSON 里包含tool_calls字段说明模型正确识别了工具并准备调用。实际执行还需要 MCP Server 配合但这一步可以确认 TaoToken 的 Key 和模型接入是正常的。5. 常见报错排查401、local proxy failed、reading choices、OAuth配置过程中最容易踩的坑集中在几个报错上。这一节按报错信息逐个排查。401 Unauthorized这是最常见的错误说明认证失败。可能的原因有三个TaoToken 的 API Key 填错了、Key 过期了、或者请求头格式不对。先检查配置文件里的apiKey字段是否和 TaoToken 控制台里的一致注意不要有多余的空格。然后确认请求头是Authorization: Bearer 你的KeyBearer 和 Key 之间有一个空格。如果 Key 刚创建不久等一分钟再试有时候服务端同步有延迟。local proxy failed这个报错通常出现在 MCP Server 启动阶段提示本地代理连接失败。原因是 MCP Server 尝试连接 Penpot 实例时网络不通。检查penpot.baseUrl是否写对端口是否开放。如果你用的是 Docker 部署的 Penpot确认容器端口映射是否正确。在终端里用curl http://localhost:9001/api/health测试一下 Penpot 的 API 是否可达。如果返回连接拒绝说明 Penpot 服务本身没跑起来。reading choices 报错这个错误一般出现在 AI 客户端解析模型响应时提示读取choices字段失败。原因是模型返回的 JSON 格式不符合预期可能是 TaoToken 的 Base URL 配错了或者 Model ID 填了一个不存在的模型。检查ai.baseUrl是否是https://taotoken.net/api注意不要漏掉/api路径。然后确认ai.modelId是 TaoToken 支持的模型 ID去模型列表页核对一下。如果用的是 Claude 系列模型Model ID 的格式和 OpenAI 不同要按 TaoToken 文档里的写法填。OAuth 相关报错如果你在配置 Penpot 的访问令牌时看到 OAuth 错误说明令牌的授权范围不对。Penpot 的访问令牌需要包含design:read和design:write权限如果只勾了读权限写入操作会失败。去 Penpot 的个人设置里重新生成令牌确保勾选正确的权限范围。另外令牌的有效期也要注意过期的令牌会直接返回 401。MCP Server 启动后客户端连不上有时候 MCP Server 日志显示正常运行但 Claude Code 或 Cline 里就是看不到工具。这种情况通常是客户端的 MCP 配置路径写错了。检查claude_desktop_config.json里的command和argscommand要用绝对路径或者确保在 PATH 里args里的配置文件路径也要用绝对路径。改完后重启客户端MCP Server 会在客户端启动时自动拉起。注意每次修改配置文件后都要重启 MCP Server 和 AI 客户端否则改动不会生效。这是最容易忽略的一点。6. 把 Penpot MCP 接进日常开发流程的实用建议配置跑通之后怎么把它用起来才是关键。这里分享几个实际场景。第一个场景是设计规范检查。你可以让 AI 通过 MCP 读取整个项目的 Design Tokens然后对比团队的设计规范文档自动找出不一致的地方。比如某个按钮用了#FF5722而不是规范里的#E64A19AI 可以直接定位到具体图层并给出修改建议。这比人工逐个检查效率高得多。第二个场景是设计稿转代码。AI 读取设计结构后可以生成对应的 React 或 Vue 组件代码。因为 Penpot 的数据本身就是基于 CSS Grid 和 Flex Layout 的生成的代码和设计稿的偏差会明显小于从截图识别的方式。你可以在 CI 流程里加一步设计稿更新后自动触发代码生成开发只需要 review 和微调。第三个场景是跨平台迁移。如果你需要把设计从 Penpot 迁移到另一个工具或者反过来MCP Server 可以作为中间层。AI 读取源平台的设计结构转换成目标平台的格式再通过 MCP 写入。整个过程可以脚本化不需要手动导出导入。关于 TaoToken 的使用建议把 Key 放在环境变量里不要硬编码在配置文件中。如果你有多个项目可以给每个项目创建单独的 Key方便追踪用量和权限控制。TaoToken 的控制台里可以查看每个 Key 的调用记录排查问题时很有用。长期做 AI 编码或者 Agent 开发的团队可以考虑 TaoToken 的 Coding Plan它提供了更稳定的调用配额和更低的延迟。对于需要频繁调用模型的设计工作流来说这个方案比按次计费更划算。具体可以看https://taotoken.net/coding-plan。最后说一个实际踩过的坑Penpot 的 MCP Server 在读取大型设计文件时返回的数据量可能很大如果模型上下文窗口不够会被截断。解决办法是在调用时指定只读取特定页面或特定图层而不是整个项目。MCP 工具的参数里通常支持pageId或layerId过滤用这个来缩小数据范围。整套流程跑下来你会发现 Penpot 的 MCP Server 加上 TaoToken 的统一 Key把设计数据和 AI 能力之间的通道打通了。设计不再是孤立的画布而是可以被程序读取、分析、修改的结构化数据。对于想把 AI 接入设计流程的开发者来说这是一条值得投入时间跑通的路径。