结合 Penpot 设计实现 UI 的思路——如何使用 Penpot + Codex
结合 Penpot 设计实现 UI 的思路——如何使用 Penpot + Codex
起因，从一次博客改版开始
前段时间，我想重新整理博客界面，于是用 Penpot 画了首页、随笔页、文章页和搜索面板。设计完成后，接下来就是把草稿还原成可以运行的页面。
我也考虑过 Figma，但其官方远程 MCP 在 Starter 计划下目前最多只有每月 6 次工具调用，不够支撑反复读取和精调。更高额度需要付费方案以及 Dev 或 Full 席位，所以这次我选择了 Penpot。
Penpot 接入 Codex
本节中的 Penpot 获取、MCP 安装与启动、连接配置和结果验证，都可以直接交给 Codex Agent 协助操作。涉及账号登录或 MCP Key 时，需要在页面中完成必要授权，并避免把密钥写入提示词、截图或代码仓库。
获取并打开 Penpot
Penpot 最简单的使用方式是网页版，不需要下载桌面客户端：
- 打开 Penpot 官网。
- 点击注册入口，或者直接访问 Penpot Cloud。
- 注册并登录账号，新建一个项目和设计文件。
如果只是按照本文体验 Penpot + Codex，优先使用网页版即可。
需要把 Penpot 部署在自己的服务器时，再参考官方自托管指南。自托管需要 Docker、Docker Compose 以及基本的服务器维护能力。注意，“本地 MCP”只代表 MCP 服务运行在本机，并不要求把整个 Penpot 也安装到本机；它同样可以连接浏览器中打开的 Penpot Cloud。
MCP 用于连接 Penpot 与 Codex。连接完成后，Codex 可以读取当前设计页面的结构、组件、样式和设计变量，并结合本地项目完成 UI 实现。
MCP 地址速查
| 用途 | 当前地址 |
|---|---|
| MCP 官方文档 | https://help.penpot.app/mcp/ |
| MCP GitHub 源码 | https://github.com/penpot/penpot/tree/main/mcp |
| MCP npm 包 | https://www.npmjs.com/package/@penpot/mcp |
| 远程 MCP 格式 | https://design.penpot.app/mcp/stream?userToken=YOUR_MCP_KEY |
| 本地插件地址 | http://localhost:4400/manifest.json |
| 本地 MCP 地址 | http://localhost:4401/mcp |
远程 MCP 地址不要手动拼接，应在 Penpot 的 Your account → Integrations → MCP Server 中直接复制。地址中的 userToken 是个人密钥，不能公开。
远程连接
- 打开 Penpot 的
Your account → Integrations → MCP Server。 - 启用 MCP Server，生成并保存 MCP Key。
- 复制包含
userToken的服务器 URL。 - 在 Codex 中添加 MCP Server，填入该 URL。
- 在 Penpot 中打开目标文件，选择
File → MCP Server → Connect。 - 重新加载 Codex 工具，确认 Penpot 工具可用。
远程方式配置简单，适合优先使用。
本地连接
启动本地服务：
npx -y @penpot/mcp@stable
在 Penpot 中加载插件：
http://localhost:4400/manifest.json
在 Codex 中添加 MCP Server：
http://localhost:4401/mcp
使用期间需要保持终端进程和 Penpot 插件运行。如果浏览器阻止网页访问本地网络，需要开启本地网络权限或更换浏览器。
验证连接
在 Penpot 中打开并聚焦目标页面，然后让 Codex 执行只读检查：
请读取 Penpot 当前页面，列出页面名称、主要画板、组件和设计变量。
只读取，不要修改设计。
返回内容与当前页面一致，即可开始实现。
注意：MCP 作用于 Penpot 当前聚焦的页面。MCP Key 不要写入代码仓库，也不要出现在截图中。
使用流程：草稿 → 代码还原 → 精调
| 阶段 | 目标 | 完成标准 |
|---|---|---|
| 草稿 | 在 Penpot 中确定页面结构、内容层级和交互方式 | 主要页面和状态已经明确 |
| 代码还原 | 让 Codex 读取设计与项目，生成可运行页面 | 结构正确，原有数据和功能正常 |
| 精调 | 在浏览器中对照设计，修正视觉与响应式差异 | 关键视口下的页面符合设计预期 |
日常使用时，只需记住下面这条流程：
打开 Penpot 目标页面
→ 连接 MCP
→ 让 Codex 读取设计和项目
→ 完成第一版代码还原
→ 在浏览器中对照
→ 按差异逐项精调
浙公网安备 33010602011771号