Penpot MCP 安装配置与 AI 设计转代码实战教程

Penpot 是目前最成熟的开源设计平台，常被视为 Figma 的开源替代；其官方 MCP 服务器把设计文件的结构、样式与组件数据开放给 AI 编程 Agent，让「读取设计稿，直接生成前端代码」成为一条流畅的日常工作流。本教程以 ZCode 为 Agent 侧主线，完整讲解 Penpot 官方 MCP 服务器的本地部署、Penpot 插件的连接方法与 ZCode 的 MCP 接入配置，并通过「从设计稿生成可运行登录页面」的案例演示设计转代码流程，文末给出 Penpot 与 Figma 的横向对比，帮助你按团队现状选择合适的工具组合。

前置教程

如想快速开始学习本教程，你可能需要先完成以下前置教程：

• MCP概念详解与应用完整教程，理解 MCP 协议、客户端、服务器与传输方式的基本概念，本教程不再展开这些基础内容。
• Node.js和Npm安装与使用教程，Penpot MCP 服务器的构建与运行依赖 Node.js 与 npm。
• Blender MCP安装配置与AI建模实战教程，ZCode 的 MCP 配置方法与「本地服务器 + 宿主插件」的运行模式，本教程与之一脉相承。

资源下载

• Penpot 官网（云版注册），设计稿的编辑环境，浏览器中直接使用。
• penpot-mcp 官方仓库（GitHub），MCP 服务器与 Penpot 插件的源码仓库。
• Penpot MCP 官方文档，安装说明与配置项参考。

1. Penpot 与 Penpot MCP 是什么

1.1 开源的设计平台

Penpot 是由 Kaleidos 团队主导的开源设计与原型工具，采用 MPL-2.0 许可证：官方云版注册即用，对数据私有有要求的团队还可以用 Docker 在自己的服务器上完整自托管。它原生以 Web 标准（SVG、HTML、CSS）描述设计数据，这个基因让「设计稿转代码」比私有格式的设计工具更自然——AI 拿到的数据本身就贴近最终的前端代码。

1.2 官方 MCP 服务器的架构

Penpot 官方提供了 MCP 服务器（仓库 penpot/penpot-mcp），它由两个本地组件组成：一个是 MCP 服务器进程，负责与 AI Agent 对话；一个是安装在 Penpot 内的官方插件，负责在 Penpot 中执行实际的设计数据读写。插件与服务器之间通过本地 WebSocket 通道通信，整体链路如下：

这个结构与 Blender MCP 的「宿主程序 + 插件 + 本地服务器」三层模式同构：MCP 服务器本身不懂设计，真正的读写发生在 Penpot 内的插件里。由此带来一个与 Blender MCP 相同的使用前提——浏览器里加载插件的 Penpot 页面必须保持打开，插件面板不能关闭，否则 Agent 的所有设计相关调用都会失败。

1.3 它能做什么

Penpot MCP 把 Penpot 的 Plugin API 完整暴露给 AI Agent，Agent 拿到工具后可以在 Penpot 中执行查询与变换，官方将其归纳为三类工作流：

本教程聚焦第一类。三类工作流共用同一套接入配置，打通之后其余两类只需更换提示词。

2. 环境准备

2.1 注册 Penpot 云版账号

访问 design.penpot.app 注册账号并登录。本教程使用官方云版；自托管实例同样适用，只需把后文中的云版地址替换为你的实例地址。

2.2 安装 Node.js

Penpot MCP 服务器要求 Node.js 22 或更高版本。按 Node.js和Npm安装与使用教程完成安装后，在终端验证：

node --version
npm --version

2.3 确认 ZCode 环境

本教程的 Agent 侧使用 ZCode。确认本机已安装 ZCode 并能正常启动会话；ZCode 的 MCP 配置位于用户配置文件 C:\Users\<你的用户名>\.zcode\cli\config.json 的 mcp.servers 字段下，本教程第 5 章将直接编辑该文件。

3. 部署 Penpot MCP 服务器

3.1 克隆仓库与安装

选择一个长期存放项目的目录（下文以 D:\penpot-mcp 为例），克隆官方仓库并执行一键启动脚本：

git clone https://github.com/penpot/penpot-mcp.git
cd penpot-mcp
npm run bootstrap

bootstrap 会依次完成三件事：安装全部子项目依赖、构建 MCP 服务器与插件产物、在本地同时启动两个服务。首次执行需要下载依赖，耗时取决于网络状况。

3.2 认识本地端口

服务启动后，本机会监听四个端口，各有分工：

与你直接相关的是 4400（给 Penpot 插件用）和 4401（给 ZCode 用）两个端口。

3.3 验证 MCP 端点

在终端执行以下命令确认 MCP 服务器已经就绪：

curl -i http://localhost:4401/mcp

服务正常时会返回 MCP 协议层的响应（如 405 或 406 状态码，提示需要 POST 与正确的协议头），这属于预期行为——它证明端口在服务，且该端点是标准 Streamable HTTP 传输，与 ZCode 的 HTTP 接入方式完全匹配。若连接被拒绝，回到 3.1 节确认服务已启动。

4. 在 Penpot 中连接官方插件

4.1 加载 Penpot MCP 插件

MCP 服务器自己看不到设计文件，读写设计数据要靠运行在 Penpot 页面里的插件完成。加载步骤如下：

1. 登录 design.penpot.app，打开任意一个设计文件。
2. 在插件（Plugins）入口选择开发者插件的加载方式。
3. 插件地址填入 http://localhost:4400/manifest.json 并确认。
4. 插件面板打开后，点击面板中的 Connect to MCP server 按钮。

看到连接成功的提示，说明插件已通过 WebSocket 通道挂上了本地 MCP 服务器。此后使用期间保持该插件面板开启——关闭面板即断开连接，这是本教程最重要的使用习惯。

4.2 允许浏览器访问本地网络

云版 Penpot 是一个公网页面，它要连接的插件 Web 服务在 localhost 上。较新版本的 Chromium 内核浏览器（Chrome 142 起）默认拦截「公网页面访问本机服务」的行为，首次连接时会弹出本地网络访问权限请求，必须选择允许。使用 Brave 浏览器时还需对该站点关闭 Shields 防护；个别浏览器版本拦截过严时，换 Firefox 打开 Penpot 是最省事的绕行方式。

4.3 验证插件通道

插件连接成功后，其面板会显示与 MCP 服务器的连接状态。此时在 Penpot 中选中画布上的任意图层，插件面板能同步读到图层信息，说明「Penpot、插件、服务器」整条链路已经打通，可以进入 Agent 侧配置。

5. 在 ZCode 中接入 Penpot MCP

5.1 编写配置

编辑 ZCode 的用户配置文件 C:\Users\<你的用户名>\.zcode\cli\config.json，在其 mcp.servers 对象中追加一个名为 penpot 的服务器条目：

{
  "mcp": {
    "servers": {
      "penpot": {
        "type": "http",
        "url": "http://localhost:4401/mcp"
      }
    }
  }
}

配置要点：

• type: "http" 对应 Streamable HTTP 传输，是 ZCode 接入远程型 MCP 服务器的标准写法。如果你的配置文件中已经有其他服务器条目（如 chrome-devtools、github 这类 type: "stdio" 的条目），直接在同一个 servers 对象里并列追加即可，整体结构见 MCP概念详解与应用完整教程。
• url 必须以 /mcp 结尾。Penpot 的服务器同时保留了旧版 /sse 端点，配置时不要误用。
• 本地服务器无任何认证，配置中不需要令牌类字段。

保存配置后重启 ZCode，新会话开始时会自动连接该服务器。

5.2 验证配置

重启 ZCode 后打开新会话，在对话框输入：

请列出你当前可用的 MCP 工具里与 Penpot 相关的部分。

Agent 能报出若干 Penpot 工具，说明配置已生效。也可以直接进入 5.3 节的对话验证，一步到位。

5.3 对话验证工具调用

保持第 3、4 章的服务与插件均处于连接状态，在 ZCode 会话中输入：

请调用 Penpot MCP 工具，读取我当前在 Penpot 中打开的文件名称与页面里的图层统计。

连接正常时，会话中会出现 mcp__penpot__ 前缀的工具调用记录。如果工具列表为空或连接失败，见 8.2 节的常见问题与解答。

6. 实战：从设计稿生成可运行页面

本章用一个完整案例走通「设计稿到代码」流程。设计稿使用一个简单的登录页面，包含标题、两个输入框、一个主按钮和一条辅助链接。

6.1 准备设计稿

实战素材有三种准备方式，任选其一：

• 直接绘制：在 Penpot 中新建文件，用基础图形与文本搭一个登录页。
• 使用模板：Penpot 的模板库（Templates）中有现成的登录页与落地页模板，从 Dashboard 新建文件时套用即可。
• 从网页自动生成：按 6.4 节的方法，给 ZCode 一个真实登录页的网址，让它在 Penpot 中自动生成对应的设计稿，再对生成结果做后续的转代码练习——这也是本教程推荐的方式，它顺便把反向工作流也练了一遍。

设计稿准备就绪后，打开该文件，确认页面中有一个完整的 Frame。由于 Penpot 的设计数据原生采用 Web 标准描述，输入框的圆角、按钮的填充色、间距值都会以 CSS 语义直接暴露给 Agent，还原精度天然有保障。检查第 4 章的插件面板处于连接状态，然后保持该文件页面打开。

6.2 让 ZCode 读取设计并生成代码

切换到 ZCode 会话，输入：

请读取我在 Penpot 中当前打开的登录页设计，获取页面结构与样式数据，
将其还原为一个单文件的 HTML 页面，样式内联在 style 标签中，保存到 penpot-login/index.html。

ZCode 会调用 Penpot MCP 工具读取文件与图层信息，必要时分页面、分图层逐级取数，然后生成代码并写入文件。生成过程中你可以在会话里看到每一次工具调用的名称与参数，这正是 MCP 方式透明可溯的体现。

6.3 浏览器验证与迭代修正

用浏览器打开生成的页面，与 Penpot 原稿并排对照。首版代码通常已接近原稿，局部偏差可以继续对话修正：

对比生成页面与 Penpot 设计稿，主按钮的填充色和卡片圆角还原不到位，
请重新读取这两个元素的样式数据后修正 CSS。

迭代两三轮后，页面与原稿的偏差一般能收敛到肉眼难以分辨的程度。确认效果满意后，这套流程即可沉淀为你日常的前端起步方式：设计定稿、AI 出码、人工微调。

6.4 反向工作流：从网页或代码生成设计文件

接入打通后，反向工作流同样可用：让 ZCode 读取一段网页代码，调用 Penpot 工具在当前文件中创建对应的图形与文本图层，把页面还原为设计稿。它支持两种输入。

第一种是目标网站地址。ZCode 先抓取页面，分析结构、文案、配色、字号与圆角等样式信息，再在 Penpot 中逐层创建内容，提示词示例如下：

请抓取这个登录页网址，分析其页面结构、配色与字体样式，
然后在 Penpot 当前文件中创建一个对应的设计稿 Frame，按区块分组并命名。

第二种是本地 HTML 文件，例如把第 6.2 节生成的页面再搬回设计稿，用于组件库整理或设计走查：

请读取 penpot-login/index.html 的页面结构，在 Penpot 当前文件中创建对应的图层，
按区块分组并命名。

对还原度建立合理预期：整体布局、配色体系、字体层级可以较好还原；图片素材、动效与轮播等复杂组件需要人工补充。抓取目标网站仅建议用于学习练习，注意遵守目标站点的版权声明。

6.5 导出与导入设计文件

Penpot 支持把文件导出为 .penpot 格式的本地文件：在工作区或 Dashboard 的文件卡片菜单中选择下载即可。反向操作同样简单，在 Dashboard 中导入 .penpot 文件，它就会作为新文件进入你的空间。

这个能力让设计稿可以像代码一样留存与分发。你可以把 6.4 节生成的设计文件导出留存，分享给其他学习者，也可以导入到自己搭建的自托管实例；为团队准备教学素材时，先生成、再导出、最后分发，一套设计文件就能支撑多人练习。已有 Figma 设计资产的读者，还可以通过 Figma Community 中的 Penpot Exporter 插件把设计稿转为 .penpot 文件导入，完成存量资产的迁移。

7. Penpot 与 Figma 的对比

7.1 平台与 MCP 架构对比

两个工具都能支撑「设计稿转代码」这条工作流，产品形态与技术路径有明显差异：

数据格式是最影响转代码质量的一项：Penpot 的图层属性与 CSS 属性一一对应，Agent 拿到即可用；Figma 则依赖官方服务器把私有格式翻译成代码上下文，翻译质量由官方持续打磨。

7.2 工作流体验的差异

Penpot 的流程是「本地服务器常驻、插件桥接、Agent 自由读写当前打开的文件」，一次配置长期使用，读写双向都走同一通道。Figma 的流程围绕「选中驱动与链接驱动」展开：在画布中选中内容或粘贴设计链接，Agent 据此获取上下文，交互粒度更细，设计变量与组件映射的能力也更精细。

7.3 选型建议

按设计资产的位置与团队工具链决定：新项目、看重开源与自托管、希望任意 MCP 客户端都能接入，选 Penpot；团队设计资产深度沉淀在 Figma、已依赖其组件体系与协作流程，继续用 Figma 的 MCP 方案。两者并不互斥：设计稿可以经 Penpot Exporter 插件或 SVG 导出导入在两个平台间迁移，MCP 接入也可以在同一个 ZCode 配置里并存——按 5.1 节的模式并列追加一个条目、换一个端点地址即可，随项目灵活切换。

8. 总结与常见问题

8.1 核心内容回顾

• Penpot 是开源的设计平台，官方 MCP 服务器（penpot/penpot-mcp）把设计数据的完整读写能力开放给 AI Agent，云版与自托管均可使用。
• 其架构为「Penpot 页面内插件、本地 MCP 服务器、Agent」三层，插件经 WebSocket 桥接服务器，使用期间须保持插件面板开启。
• MCP 服务器经 npm run bootstrap 一键部署，Agent 侧端点为 http://localhost:4401/mcp；ZCode 在 config.json 的 mcp.servers 中以 type: "http" 直连，工具名以 mcp__penpot__ 为前缀。
• Penpot 与 Figma 各有擅长的场景：前者开源开放、设计数据贴近 Web 标准，后者组件与协作生态成熟；两条路线的 ZCode 配置写法完全一致，切换成本只有端点地址一个字段。

8.2 常见问题与解答

问：ZCode 连不上 Penpot MCP 端点怎么办？

答：按顺序检查 bootstrap 启动的服务是否在运行、curl 访问 4401 端口是否有响应、config.json 中 penpot 条目的 JSON 语法是否正确、修改配置后是否重启过 ZCode。最常见的情形是终端窗口被关闭导致本地服务退出——bootstrap 启动的服务随终端存活，日常使用建议把启动命令放入独立终端或注册为后台服务；其次是配置问题：url 写成 /sse 结尾（应使用 /mcp）、JSON 多余或缺少逗号、修改后没有重启 ZCode。

问：工具调用成功，为什么读不到设计数据？

答：设计数据的读取链路经过「Penpot 页面、插件、WebSocket、MCP 服务器」四环，任一环断开都会导致空结果。依次确认：Penpot 文件页面还开着、插件面板没有关闭、插件面板显示连接正常、目标文件确实在当前页面中打开。跨文件读取时，Agent 只能访问当前打开的文件。

问：浏览器提示本地网络访问被拦截？

答：这是 Chromium 内核对公网页面访问 localhost 的安全限制。首次连接弹出权限请求时选择允许；Brave 浏览器需关闭该站点的 Shields；拦截过严时换 Firefox 打开 Penpot。自托管 Penpot 的用户可以把实例与插件放在同一网络策略下，从根源避开该限制。

问：国内网络环境有什么要注意的？

答：Penpot 云版服务位于海外，注册登录与文件加载偶有缓慢。本地部署的 MCP 服务器、插件服务与 ZCode 之间的通信全部发生在本机回环地址上，不经过外网，因此设计转代码链路本身不受网络波动影响；只有打开 Penpot 编辑器这一步依赖云版连通性。对连通性要求高的团队可考虑自托管 Penpot。

问：Penpot 云版会有功能限制吗？

答：设计编辑与本教程涉及的 MCP 能力在云版全部可用。云版与自托管的功能差异主要在企业协作管理层面，与设计转代码链路无关。

问：自托管 Penpot 也支持这套 MCP 流程吗？

答：支持。MCP 服务器与插件运行在你自己的机器上，只要插件能连上你的 Penpot 实例即可，配置方法与云版一致。

问：ZCode 能连 Figma 的 MCP 吗？

答：Figma 远程 MCP 服务器仅向其指定名单内的客户端开放，ZCode 暂未在名单中；名单动态变化，可关注官方进展。设计资产在 Figma 的团队也可以通过 Figma 桌面端内置的本地 MCP 服务器接入，配置写法与第 5 章一致。

问：生成代码只支持 HTML 吗？

答：Penpot MCP 暴露的是设计数据本身，技术栈由提示词决定。让 ZCode 输出 Vue 单文件组件、React 组件或遵循项目既有组件体系的代码都可以，声明目标栈即可。