1. 项目概述：当设计工具遇上AI智能体

最近在探索AI智能体（Agent）的落地场景时，我一直在思考一个问题：如何让AI不只是生成文本或代码，而是能真正“操作”我们日常使用的专业软件，成为得力的工作伙伴？直到我发现了 montevive/penpot-mcp 这个项目，它恰好提供了一个绝佳的范本。简单来说，这是一个为 Penpot（一款开源的Figma替代品）设计的 MCP（Model Context Protocol）服务器。

如果你对 MCP 还不太熟悉，可以把它理解为一套“翻译”协议。它能让像 Claude、Cursor 这类搭载了 AI 能力的 IDE 或聊天助手，理解并安全地调用外部工具和系统的功能。而 penpot-mcp 就是专门为 Penpot 设计的“翻译官”。通过它，你的 AI 助手可以直接在 Penpot 文件中执行创建画板、绘制形状、修改图层属性、甚至进行简单的布局调整等操作。这不仅仅是“通过描述生成设计稿”那么简单，而是实现了 AI 对设计工具的“直接操控”，让设计迭代、批量修改、资产整理等重复性工作变得自动化、智能化。

这个项目非常适合三类人：一是希望提升设计工作流效率的 UI/UX 设计师或前端工程师；二是对 AI 智能体应用开发感兴趣的开发者，可以将其作为学习 MCP 协议和工具集成的最佳案例；三是任何对“AI+工具”自动化抱有好奇心的技术爱好者。接下来，我将深入拆解这个项目的实现逻辑、核心配置、实操步骤以及我趟过的那些坑，带你从零开始，把它用起来。

2. 核心架构与 MCP 协议深度解析

2.1 MCP 协议：AI 的“手和眼睛”

要理解 penpot-mcp ，必须先搞懂 MCP 是什么。你可以把大型语言模型（LLM）想象成一个极具智慧的大脑，但它被困在了一个封闭的房间里。它知道很多事情，但无法直接操作电脑上的软件、读取特定文件或查询数据库。MCP 就是这个房间上开的一扇安全、可控的“窗户”，并为大脑配上了可以伸出去的“手”和“眼睛”。

MCP 定义了一套标准的通信方式。一个 MCP 服务器（比如 penpot-mcp ）就像是一个专业的工具管家，它对外提供一系列定义好的“工具”（Tools）和“资源”（Resources）。AI 客户端（如 Claude Desktop）通过 MCP 与服务器对话，说：“请使用‘创建矩形’这个工具，参数是位置 (100,200)，大小 300x400。” 服务器收到指令后，将其翻译成 Penpot API 能理解的命令并执行，然后将结果返回给 AI 客户端。

这种架构有几个关键优势：

  1. 安全性 ：AI 客户端不直接拥有系统权限，它只能通过 MCP 服务器暴露的有限工具进行操作，权限被牢牢锁在服务器这一层。
  2. 标准化 ：无论后端是 Penpot、Photoshop 还是一个数据库，只要它们都通过 MCP 服务器暴露接口，AI 客户端就能用同一种方式“说话”，降低了集成复杂度。
  3. 灵活性 ：开发者可以为任何软件或服务编写 MCP 服务器，极大地扩展了 AI 的能力边界。

penpot-mcp 就是这个理念在开源设计工具领域的一次具体实践。

2.2 Penpot-mcp 的组件与工作流

这个项目的核心是一个用 TypeScript 编写的 Node.js 服务器。它主要包含以下几个部分：

  1. MCP 协议适配层 ：负责实现 MCP 协议规范，处理来自客户端的连接、认证和标准化的请求/响应格式。
  2. Penpot API 客户端层 ：封装了对 Penpot 后端 REST API 的所有调用。Penpot 本身提供了完善的 API，用于管理文件、页面、图层等。
  3. 工具（Tools）抽象层 ：这是业务逻辑的核心。它将设计操作（如“创建画板”、“修改填充色”）封装成一个个独立的工具函数。每个工具都明确定义了所需的输入参数（如名称、类型、描述），以便 AI 客户端理解如何调用。
  4. 资源（Resources）提供层 ：除了主动操作的工具，MCP 还可以提供“资源”，比如“列出当前文件的所有页面”或“获取某个图层的详细信息”。这相当于给 AI 提供了“查看”的能力，让它能基于现有上下文做出决策。

其工作流如下图所示（概念性描述）：

  • 步骤1 ：用户在 AI 客户端（如 Claude Desktop）中提出自然语言请求，例如：“在‘首页’画板的左上角添加一个蓝色的按钮，上面写‘提交’。”
  • 步骤2 ：AI 客户端分析请求，识别出需要调用 penpot-mcp 提供的工具（可能是 create_rectangle 和 add_text ），并组装参数。
  • 步骤3 ：AI 客户端通过 MCP 协议向 penpot-mcp 服务器发送结构化请求。
  • 步骤4 ： penpot-mcp 服务器验证请求，调用对应的 Penpot API，在指定的 Penpot 文件和画板上执行创建图形和文本的操作。
  • 步骤5 ：操作完成后，服务器将结果（成功或失败信息，有时包含新图层的ID）返回给 AI 客户端。
  • 步骤6 ：AI 客户端将结果转化为自然语言反馈给用户：“已完成。已在‘首页’画板创建了一个蓝色矩形和‘提交’文本。”

注意 ：当前版本的 penpot-mcp 可能尚未实现如此复杂的多工具组合推理，这更多依赖于 AI 客户端自身的能力。但它的价值在于提供了这些基础工具，为未来的智能操作铺平了道路。

3. 环境准备与项目配置详解

3.1 基础环境搭建

要运行 penpot-mcp ，你需要准备以下几个基础环境：

  1. Node.js 与 npm ：这是项目的运行基础。建议安装最新的 LTS 版本（如 18.x 或 20.x）。你可以从 Node.js 官网下载安装包，或者在 macOS/Linux 上使用 nvm 进行版本管理，这样更灵活。
  2. Penpot 实例 ：你需要一个可以访问的 Penpot 后端。有两种选择：
    • 使用官方云端服务 ：直接注册 penpot.app ，这是最简单的方式，无需自维护。
    • 自托管 Penpot ：如果你对数据隐私有更高要求，或者想进行深度定制，可以参考 Penpot 官方文档，使用 Docker 在本地或自己的服务器上部署。这对于开发调试 penpot-mcp 本身也更方便。
  3. AI 客户端 ：你需要一个支持 MCP 协议的客户端来连接和使用 penpot-mcp 。目前最主流的选择是 Claude Desktop 应用。确保你已安装并登录。

3.2 获取与初始化 Penpot-mcp

首先，我们需要获取项目代码并进行初始化配置。

# 1. 克隆项目仓库到本地
git clone https://github.com/montevive/penpot-mcp.git
cd penpot-mcp

# 2. 安装项目依赖
npm install
# 如果网络状况不佳，可以考虑使用淘宝镜像：npm install --registry=https://registry.npmmirror.com

安装完成后，你会看到 node_modules 文件夹和 package.json 等文件。接下来是最关键的配置环节。

3.3 核心配置文件解析

项目通常通过环境变量或配置文件来设置连接参数。我们需要配置 penpot-mcp 如何连接到你的 Penpot 实例。

1. 创建环境变量文件 在项目根目录下创建一个名为 .env 的文件（如果不存在）。这个文件用于存储敏感信息， 切记不要将其提交到版本控制系统 。

2. 配置关键参数 打开 .env 文件，你需要填入以下核心信息：

# Penpot 实例的基础 URL
PENPOT_BASE_URL=https://your-penpot-instance.com
# 如果是官方云端，则是：https://penpot.app

# Penpot 访问令牌 (Access Token)
PENPOT_ACCESS_TOKEN=your_super_long_access_token_here

# （可选）默认操作的文件 ID，如果不设置，AI 可能需要你指定文件
PENPOT_DEFAULT_FILE_ID=your_default_file_id_here

# （可选）MCP 服务器监听的端口，默认可能是 3000
PORT=3000

如何获取 PENPOT_ACCESS_TOKEN ？ 这是认证的关键。登录你的 Penpot 网页端。

  1. 点击右上角个人头像，进入 “设置” (Settings) 。
  2. 在左侧菜单中找到 “访问令牌” (Access Tokens) 。
  3. 点击 “生成新的令牌” (Generate new token) 。
  4. 为其起一个易于识别的名字，例如 “MCP-Server”。
  5. 生成后， 立即复制 弹出的令牌字符串。它只会显示一次，丢失后需要重新生成。

如何获取 PENPOT_DEFAULT_FILE_ID ？ 在 Penpot 中打开你想要默认操作的设计文件。观察浏览器的地址栏，URL 格式通常类似于 https://penpot.app/#/workspace/.../file/file-id 。其中 file-id 就是你需要的那一串字符。复制它即可。

实操心得 ：在开发初期，我强烈建议设置 PENPOT_DEFAULT_FILE_ID 。这能极大简化测试流程，因为你的大部分操作可能都集中在一个测试文件上。等流程跑通后，再尝试让 AI 动态选择文件。

4. 运行服务器与客户端连接实战

4.1 启动 MCP 服务器

配置好环境变量后，启动服务器就很简单了。根据 package.json 中的脚本定义，通常使用以下命令：

# 开发模式启动，带有热重载，方便调试
npm run dev

# 或者，生产模式启动
npm start

如果一切正常，你将在终端看到类似这样的输出：

Server is running on http://localhost:3000
Penpot MCP server initialized.

这表明你的 penpot-mcp 服务器已经在本地 3000 端口运行起来了。它正在等待 MCP 客户端（如 Claude Desktop）的连接。

4.2 配置 Claude Desktop 连接

这是让 AI 真正“活”起来的关键一步。我们需要告诉 Claude Desktop 这个 MCP 服务器的存在。

1. 定位 Claude Desktop 配置目录

  • macOS : ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows : %APPDATA%\Claude\claude_desktop_config.json
  • Linux : ~/.config/Claude/claude_desktop_config.json

2. 编辑配置文件 用文本编辑器（如 VS Code）打开这个 JSON 文件。如果文件不存在，就创建一个。

3. 添加 MCP 服务器配置 在配置文件中，你需要添加一个 mcpServers 对象。以下是针对本地运行的 penpot-mcp 的配置示例：

{
  "mcpServers": {
    "penpot": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-penpot"
      ],
      "env": {
        "PENPOT_BASE_URL": "https://penpot.app",
        "PENPOT_ACCESS_TOKEN": "your_actual_token_here",
        "PENPOT_DEFAULT_FILE_ID": "your_default_file_id_here"
      }
    }
  }
}

重要说明 ：

  • command 和 args ：这里使用了 npx 直接运行已发布的 NPM 包 @modelcontextprotocol/server-penpot 。这是项目作者可能提供的打包后的服务器版本，是最简单的连接方式。如果你在本地开发，想连接自己刚刚启动的服务器，配置会有所不同，可能需要使用 "command": "node" 并指向你的本地脚本，或者配置为 "url": "http://localhost:3000" （如果服务器支持 SSE 传输）。 具体方式请务必查阅 penpot-mcp 项目 README 的最新说明 ，因为 MCP 的连接方式（标准输入输出 vs. HTTP/SSE）会影响配置。
  • env ：这里的环境变量会传递给 MCP 服务器进程。其作用与我们在项目 .env 文件中设置的一样。

4. 重启 Claude Desktop 保存配置文件后， 完全退出并重新启动 Claude Desktop 应用 。只有重启后，新的 MCP 配置才会被加载。

4.3 验证连接与初步测试

重启 Claude Desktop 后，打开聊天界面。你可以尝试用一些简单的指令来测试连接是否成功：

  • “你能使用 Penpot 工具吗？”
  • “列出我的 Penpot 文件。”
  • “在默认文件中创建一个名为‘测试画板’的新画板。”

如果配置正确，Claude 应该能识别出可用的 Penpot 工具，并尝试执行你的命令。你可以在 Penpot 网页端刷新页面，查看画板或图形是否被成功创建。

踩坑记录 ：我第一次配置时，犯了一个低级错误：在配置文件中错误地转义了 JSON 字符串，导致环境变量没有被正确传递。Claude 一直回复“找不到 Penpot 工具”。解决办法是使用 JSON 在线校验工具检查配置文件格式，确保所有引号和逗号都是正确的。另一个常见问题是令牌权限不足，确保生成的访问令牌具有足够的权限（通常是“读写”权限）。

5. 核心工具详解与高级使用场景

5.1 内置工具功能解析

penpot-mcp 目前实现了一系列基础但强大的工具。理解每个工具的能力和参数，是有效下达指令的前提。以下是一些典型工具及其应用：

  1. list_files / get_file ：

    • 功能 ：列出你有权访问的所有文件，或获取特定文件的详细信息。
    • 使用场景 ：让 AI 了解你的工作区内容。“帮我找一下那个关于‘用户仪表盘’的设计文件。”

  2. create_artboard ：

    • 功能 ：在指定文件的指定页面中创建新画板。
    • 关键参数 ： fileId （文件ID）， pageId （页面ID）， name （画板名）， x , y （坐标）， width , height （尺寸）。
    • 使用场景 ：快速搭建框架。“在‘登录页’这个页面，顶部创建一个 1440x900 的画板，命名为‘桌面端视图’。”

  3. create_rectangle , create_circle , create_text ：

    • 功能 ：创建基础图形和文本图层。
    • 关键参数 ：除了位置尺寸，还有 fills （填充色，如 #4A90E2 ）， strokes （描边）， text （文本内容）， font-size 等。
    • 使用场景 ：快速添加 UI 元素。“在刚才创建的画板里，中间加一个圆角矩形按钮，蓝色填充，白色文字‘登录’。”

  4. update_shape ：

    • 功能 ：修改已有图层的属性。
    • 关键参数 ： shapeId （图层ID）， 以及需要更新的属性如 fills , width 等。
    • 使用场景 ：批量修改或调整样式。“把所有按钮的蓝色改成深蓝色（ #357ABD ）。”

  5. list_layers / get_layer ：

    • 功能 ：查看画板内的图层结构或获取某个图层的详细信息。
    • 使用场景 ：让 AI 感知当前设计状态，以便进行精确操作。“当前画板里有哪些文本图层？”

5.2 组合使用与复杂指令构建

AI 的威力在于将简单工具组合起来完成复杂任务。虽然当前的 penpot-mcp 和 AI 客户端可能还无法完全自主规划多步骤任务，但我们可以通过更精确的指令来引导。

示例：创建一个简单的用户卡片 你可以尝试这样对 Claude 说： “请在我的默认 Penpot 文件中，执行以下操作：1. 在页面1创建一个 300x400 的画板，命名为‘用户卡片’。2. 在该画板内 (20,20) 的位置创建一个 60x60 的圆形，灰色填充（ #CCCCCC ）。3. 在圆形下方 (20, 90) 的位置创建文本‘张三’，字体大小 16，颜色黑色（ #333333 ）。4. 在‘张三’下方 (20, 120) 创建文本‘前端工程师’，字体大小 12，颜色灰色（ #666666 ）。”

这样的指令虽然冗长，但结构清晰，AI 更容易将其拆解为多个连续的 create_artboard , create_circle , create_text 工具调用。

5.3 高级场景：设计系统维护与批量操作

这才是 penpot-mcp 潜力巨大的地方。想象一下这些场景：

  • 批量更新颜色主题 ：你的品牌色从蓝色系升级为绿色系。你可以让 AI “找出所有使用了 #4A90E2 这个颜色的填充和描边，将它们替换为 #2E8B57 ”。这需要 AI 结合 list_layers 、 get_layer 进行分析，再调用 update_shape 进行修改。
  • 生成标准化组件库 ：你可以描述一个按钮组件的多种状态（默认、悬停、禁用）。AI 可以按规格创建出主按钮，然后通过复制和修改属性，快速生成其他状态的按钮，并保持间距和对齐。
  • 设计稿标注导出辅助 ：虽然不能直接导出标注，但 AI 可以帮你整理信息。“列出‘首页’画板中所有文本图层的字体、字号和颜色，以表格形式输出。” 这能极大节省手动整理的时间。

要实现这些高级场景，一方面依赖于 penpot-mcp 未来提供更强大的工具（如“按条件查找图层”、“批量操作”），另一方面也取决于 AI 客户端复杂任务规划能力的提升。

6. 常见问题排查与调试技巧

在实际操作中，你肯定会遇到各种问题。这里汇总了我遇到的一些典型情况及其解决方法。

6.1 连接与配置问题

问题现象 可能原因 排查步骤与解决方案
Claude 完全无法识别 Penpot 工具 1. MCP 配置未生效
2. 服务器启动失败
3. 命令路径错误		 1. 重启 Claude Desktop ，这是最常被忽略的步骤。
2. 检查终端里 penpot-mcp 服务器是否在运行且无报错。
3. 核对 claude_desktop_config.json 中的 command 和 args ，确保指向正确的可执行文件或服务器地址。
Claude 识别到工具，但执行时报“认证失败”或“无权限” 1. Penpot 访问令牌无效或过期
2. 令牌权限不足
3. PENPOT_BASE_URL 配置错误		 1. 登录 Penpot 后台，重新生成访问令牌，并更新到环境变量和 Claude 配置中。
2. 生成令牌时，确保勾选了所有必要的权限（通常是读写权限）。
3. 确认 PENPOT_BASE_URL 末尾没有多余的斜杠 / ，并且是准确的实例地址。
操作成功但 Penpot 界面无变化 1. 操作了非当前查看的文件/页面
2. Penpot 页面未刷新
3. 文件ID或页面ID错误		 1. 明确指定 fileId 和 pageId ，或确认 DEFAULT_FILE_ID 设置正确。
2. 在 Penpot 网页端手动刷新页面。
3. 使用 list_files 和 list_pages 工具确认正确的 ID。

6.2 操作执行问题

问题现象 可能原因 排查步骤与解决方案
AI 理解指令但调用工具参数错误 1. AI 对参数格式理解有偏差
2. 工具参数要求严格		 1. 简化并精确化你的指令 。例如，明确说“创建一个 填充色为 #FF0000 的矩形”，而不是“创建一个红色矩形”。
2. 查阅项目文档，了解每个工具确切的参数名称和类型（如 x , y 是数字， fills 是数组）。
创建的元素位置或大小不符合预期 1. 坐标原点理解偏差
2. 未考虑画板内相对位置		 1. Penpot 画布坐标原点 (0,0) 在画板的 左上角 。下达指令时需明确。
2. 对于复杂布局，可以先让 AI 获取画板尺寸 ( get_artboard )，再基于此计算相对位置。
执行速度慢或超时 1. 网络延迟（尤其连接云端 Penpot）
2. 单次操作过于复杂		 1. 这是正常现象，AI 思考、网络通信、API 调用都需要时间。
2. 将复杂任务拆分成多个简单指令依次执行。

6.3 开发与调试进阶技巧

如果你不仅仅是想使用，还想参与贡献或修改 penpot-mcp ，以下技巧会有帮助：

  1. 启用详细日志 ：在启动服务器时，可以设置环境变量 DEBUG=* 或查看项目是否支持 LOG_LEVEL=debug ，这会在终端打印出详细的请求和响应信息，是排查通信问题的利器。
  2. 使用 MCP Inspector 工具 ：Anthropic 官方提供了一些 MCP 调试工具，可以让你直接与 MCP 服务器交互，测试工具调用，而无需通过 Claude。这对于独立验证服务器功能是否正常非常有用。
  3. 阅读 Penpot API 文档 ： penpot-mcp 的本质是对 Penpot API 的封装。当你想知道某个功能是否可能实现时，直接查阅 Penpot 的 API 文档 会获得最准确的信息。你可以对比 API 的能力和现有 MCP 工具的实现，找到扩展点。

7. 未来展望与自定义扩展思路

目前 montevive/penpot-mcp 项目还处于比较早期的阶段，工具集覆盖了最基础的操作。但它的架构已经搭好，为我们指明了方向。如果你是一名开发者，完全可以基于此进行扩展。

扩展方向一：丰富工具集 现有的工具可能缺少一些实用功能，例如：

  • 对齐与分布 ：实现 align_left , distribute_horizontally 等工具。
  • 图层操作 ： group_layers （成组）、 change_layer_order （调整层级）。
  • 高级编辑 ： boolean_operation （布尔运算）、 modify_corner_radius （修改圆角）。 你可以参考现有工具的代码结构，在 src/tools/ 目录下添加新的工具文件，实现对应的 Penpot API 调用。

扩展方向二：实现“资源”提供 除了“工具”，MCP 的“资源”概念也很有用。例如，可以提供一个 current_color_palette 资源，让 AI 能读取当前文件或团队库中的颜色样式，从而在创建元素时使用一致的设计令牌。

扩展方向三：与工作流深度集成 将 penpot-mcp 与 CI/CD 管道结合。例如，在代码评审时，AI 可以自动检查关联的设计稿是否更新；或者根据 Figma/ Penpot 中的设计变更，自动生成更新日志的草稿。

这个项目的真正魅力在于，它打开了一扇门，让我们看到了 AI 与专业工具深度协同的未来。它不再是一个只能被动回答问题的聊天框，而是一个能主动操作、执行复杂任务的数字同事。从简单的创建元素开始，逐步扩展到设计系统检查、交互逻辑标注、甚至多稿对比分析，可能性是无限的。

我个人在折腾这个项目的过程中，最大的体会是： 清晰的指令是成功的一半 。在现阶段，与其期待 AI 完全自主地完成复杂设计，不如学会如何将一个设计任务拆解成一系列原子化的、参数明确的 MCP 工具调用指令。这个过程本身，就是在训练我们更结构化地思考设计。开始尝试时，可以从“帮我创建几个不同尺寸的画板”这样的简单任务做起，慢慢过渡到“把这个画板里的所有标题字体放大 2 个像素”这类批量操作。每一步成功，都会让你对“AI 作为协作者”这一角色有更深的理解。

# AI智能体
Logo
龙虾开发者社区

小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用

更多推荐

AI Agent Harness Engineering 伦理问题思考：避免偏见与滥用的技术与制度设计

概念定义核心特征AI Agent具备环境感知、自主决策、工具调用、目标达成能力的智能实体自主性、交互性、持续性、目标导向包裹在Agent外部的管控层，负责对Agent的输入、决策、输出、行为进行全链路校验和管控旁路无侵入、可动态配置、全链路留痕、风险可溯源算法偏见AI系统对特定群体（按性别、年龄、种族、地域、残疾等划分）产生的不公平、歧视性的输出或决策隐蔽性、传导性、累积性Agent滥用。

avatar 龙虾开发者社区
cover

龙虾AI零基础编程小白也能本地部署全套详细教程

avatar 龙虾开发者社区
cover

2026年5款支持openclaw小龙虾的AI剪辑工具推荐

avatar 龙虾开发者社区