Penpot MCP Server (Ancrz)

Penpot MCP服务器

通过模型上下文协议访问自托管Penpot的AI驱动设计工具。

   

______________________________________________________________________

这是什么？

一 MCP服务器 它为AI代理（如Claude Code、Cursor或任何兼容MCP的客户端）提供支持 完全程序化访问 到你自己主持 佩普特 例子AI可以通过自然语言读取、创建、修改和导出设计元素——从矩形和文本到完整的UI组件。

将其视为您的AI助手和设计工具之间的桥梁。

它解决的问题

______________________________________________________________________

建筑

graph TB
    AI["AI Agent\n(Claude Code · Cursor · Gemini CLI)"]

    subgraph SERVERS["MCP Layer"]
        MCP["penpot-mcp — Python\n68 tools · :8787\nDB reads + API writes + Plugin"]
        OMCP["Penpot MCP — Official\n~20 tools · penpot/penpot monorepo\nPlugin API only · TypeScript"]
    end

    subgraph PENPOT["Penpot Stack (Docker)"]
        PG["PostgreSQL\n:5432"]
        BE["Backend\n:6060"]
        FE["Frontend\n:9001"]
        EX["Exporter\n:6061"]
    end

    subgraph BRIDGE["Browser Plugin Bridge"]
        WS["WebSocket Server\n:4402"]
        UI["ui.html\niframe · full browser API"]
        PJ["plugin.js\nworker sandbox · penpot.*"]
    end

    AI -->|"Streamable HTTP :8787"| MCP
    AI -->|"Streamable HTTP"| OMCP

    MCP -->|"asyncpg · direct SQL"| PG
    MCP -->|"httpx · RPC API"| BE
    MCP -->|"PNG / SVG export"| EX
    MCP |"WebSocket"| WS

    OMCP |"WebSocket :4402"| WS

    WS |"ws://localhost:4402"| UI
    UI |"postMessage"| PJ
    PJ -->|"penpot.* API"| FE
    FE -.->|"proxy"| BE
    BE --> EX

    style AI fill:#7c3aed,color:#fff
    style MCP fill:#2563eb,color:#fff
    style OMCP fill:#0f766e,color:#fff
    style PG fill:#16a34a,color:#fff
    style BE fill:#ea580c,color:#fff
    style FE fill:#ea580c,color:#fff
    style EX fill:#ea580c,color:#fff
    style WS fill:#0891b2,color:#fff
    style UI fill:#0891b2,color:#fff
    style PJ fill:#0891b2,color:#fff

三层接入策略：

• 阅读 直接通过以下方式访问PostgreSQL asyncpg -快速可靠，绕过API开销
• 写入 通过Penpot的RPC API httpx --确保正确的更改跟踪和撤消历史记录
• 出口 使用Penpot的内置导出器（无头Chromium）实现像素完美的SVG/PNG输出
• 现场画布 通过浏览器插件桥（端口4402）——与 官方Penpot MCP，使两台服务器能够在同一个AI工作流程中共存并相互补充

______________________________________________________________________

技术栈

______________________________________________________________________

快速开始

先决条件

1. 自托管Penpot 通过Docker Compose运行(官方指南)
2. 码头工人 和 Docker Compose v2已安装
3. 已启用访问令牌 在您的Penpot实例中（请参见 启用访问令牌)

选项A：自动设置

git clone https://github.com/ancrz/penpot-mcp-server.git
cd penpot-mcp-server
chmod +x setup.sh
./setup.sh

该脚本将指导您完成配置、构建Docker镜像和启动服务器。

选项B：手动设置

1.克隆存储库

git clone https://github.com/ancrz/penpot-mcp-server.git
cd penpot-mcp-server

2.创建配置

cp .env.example .env

编辑 .env 您的Penpot详细信息：

# Your Penpot access token (see "Enable Access Tokens" below)
PENPOT_ACCESS_TOKEN=your-token-here

# Your Penpot database password (from your Penpot docker-compose.yml)
PENPOT_DB_PASS=your-db-password

# Public URL where you access Penpot in the browser
PENPOT_PUBLIC_URL=http://localhost:9001

3.将MCP服务添加到您的Penpot Docker堆栈中

添加 penpot-mcp 为您现有的Penpot定义服务 docker-compose.yml。参见 以便复制完整的服务定义。

4.构建并启动

docker compose up -d --build penpot-mcp

5.验证它是否正在运行

# Quick health check
curl -s http://localhost:8787/
# → {"service": "Penpot MCP", "status": "ok", "version": "0.1.0"}

# Full MCP protocol initialization
curl -s http://localhost:8787/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

您应该看到具有服务器功能的JSON响应。

______________________________________________________________________

连接您的AI代理

Penpot MCP使用 网络传输 （流式HTTP）——服务器作为Docker容器运行，客户端通过HTTP连接。这意味着：

• 服务器是 一直在跑 独立（通过Docker Compose）
• 客户端只需要URL即可连接，无需生成进程
• env 在客户端的JSON配置中是不相关的 --凭据位于服务器自己的凭据中 .env 文件（在 设置)
• 同一台机器（或网络）上的任何客户端都可以连接到 http://localhost:8787/mcp

与stdio服务器的主要区别： 对于stdio服务器（如Skill Swarm），客户端启动进程并注入env变量。对于像Penpot MCP这样的网络服务器，服务器管理自己的凭据。这 env 客户端MCP配置中的块无效。

______________________________________________________________________

克劳德代码

克劳德代码使用 "type": "http" 用于流式HTTP连接。

全球 (~/.claude.json):

{
  "mcpServers": {
    "penpot": {
      "type": "http",
      "url": "http://localhost:8787/mcp"
    }
  }
}

项目级别 (.mcp.json 在项目根目录中）：

{
  "mcpServers": {
    "penpot": {
      "type": "http",
      "url": "http://localhost:8787/mcp"
    }
  }
}

重新启动克劳德代码。你应该看看 68工具 从 penpot 运行时列出的服务器 /mcp.

注： 使用 "type": "http"，不 "streamable-http".Claude代码映射 http 内部可流式传输HTTP。使用 streamable-http 将导致架构验证错误。

______________________________________________________________________

Gemini CLI

Gemini CLI使用 httpUrl （不是 url)用于流式HTTP连接。传输是从字段名推断出来的。

配置文件： ~/.gemini/settings.json

{
  "mcpServers": {
    "penpot": {
      "httpUrl": "http://localhost:8787/mcp"
    }
  }
}

注： Gemini CLI区别于 url （苏格兰和南方能源公司运输）和 httpUrl （流式HTTP传输）。Penpot MCP使用流式HTTP，因此使用 httpUrl不 type 场需要。

______________________________________________________________________

反重力

反重力用途 serverUrl 用于基于HTTP的MCP服务器。

配置文件： ~/.gemini/antigravity/mcp_config.json

{
  "mcpServers": {
    "penpot": {
      "serverUrl": "http://localhost:8787/mcp"
    }
  }
}

注： 反重力用途 serverUrl （不是 url 或 httpUrl).如果Antigravity在Docker中运行，请确保它可以访问 localhost:8787 在主机上--您可能需要 host.docker.internal:8787 而不是 localhost:8787 这取决于你的Docker网络设置。

______________________________________________________________________

快速比较

______________________________________________________________________

示例提示

连接后，您可以向您的AI代理询问以下问题：

• *“列出我的Penpot项目”*
• *“创建一个包含电子邮件/密码字段和提交按钮的登录表单”*
• *“将登录卡框架导出为SVG”*
• *“设计系统中定义了哪些颜色？”*
• *在位置（100200）添加一条评论，说“查看此布局”*

______________________________________________________________________

交互模式：浏览器插件

Penpot MCP插件将AI代理与 现场Penpot画布，实现实时上下文感知：

• 现场选择：AI可以查询您当前选择的形状
• 脚本执行：AI可以通过Penpot插件API直接运行JavaScript

这些功能需要连接浏览器插件。66个无头工具不用它也能工作。

加载插件

1. 确保MCP服务器正在运行： docker compose up -d penpot-mcp
2. 在浏览器中打开Penpot
3. 按 Ctrl+Alt+P （或主菜单->插件管理器）
4. 将URL粘贴到输入字段中： http://localhost:8787/plugin/manifest.json
5. 点击 安装 → 允许 在“权限”对话框上
6. 点击 打开 启动插件面板

插件面板出现在右侧。当状态指示器变为绿色时，AI代理可以实时访问画布。

Penpot标志要求

Penpot后端必须具有 enable-plugins-runtime 在 PENPOT_FLAGS:

PENPOT_FLAGS=enable-login-with-password enable-registration enable-access-tokens enable-plugins-runtime

需要重新启动： 添加后 enable-plugins-runtime，重新启动两者 penpot-backend 和 penpot-frontend: ``bash docker compose restart penpot-backend penpot-frontend ``

浏览器兼容性

Chrome/Vivaldi：本地网络访问

Chrome可能会显示一个权限弹出窗口： “允许\[localhost:9001\]访问您的本地网络吗？”

1. 点击 允许 当弹出窗口出现时
2. 插件将自动连接

如果没有弹出窗口出现并且插件保持断开连接，请检查 chrome://flags/#private-network-access-respect-preflight-results --禁用它以进行本地开发。

勇敢：盾牌

1. 点击 盾牌图标 地址栏中的（狮子）
2. 禁用屏蔽 localhost:9001 （或设置为“无阻塞”）
3. 重新加载Penpot选项卡并重新连接插件

______________________________________________________________________

工具概述

服务器提供 68工具 跨越11个类别。看 TOOLS.md 以获取所有参数的完整参考。

______________________________________________________________________

配置参考

所有设置都是通过环境变量进行的。看 .env.example 对于模板。

______________________________________________________________________

启用访问令牌

Penpot需要一个功能标志来启用API访问令牌。

1.更新你的Penpot .env 文件

添加 enable-access-tokens 致你的 PENPOT_FLAGS:

PENPOT_FLAGS=enable-login-with-password enable-registration enable-access-tokens

2.重新启动Penpot

docker compose restart penpot-backend penpot-frontend

3.创建令牌

1. 在浏览器中打开Penpot
2. 点击您的头像（左下角）→ 访问令牌
3. 点击 “生成新令牌”
4. 为其命名（例如，“MCP服务器”）
5. 复制令牌并将其粘贴到您的 .env 作为 PENPOT_ACCESS_TOKEN

______________________________________________________________________

Penpot Docker集成

MCP服务器作为Docker容器与现有的Penpot堆栈一起运行。你需要将其添加到你的Penpot中 docker-compose.yml.

看 以添加确切的服务定义。关键点：

• 它连接到 penpot Docker网络（与其他Penpot服务相同）
• 这取决于 penpot-postgres （进行健康检查）以及 penpot-backend
• 它暴露了端口 8787 仅在本地主机上(127.0.0.1:8787:8787)
• 环境变量引用Docker内部主机名

______________________________________________________________________

发展

本地运行（Docker之外）

# Install uv if needed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies
uv sync

# Run the server (needs .env configured for local access)
uv run penpot-mcp

对于当地发展，点 PENPOT_DB_HOST 和 PENPOT_DB_PORT 到您的主机映射PostgreSQL端口，以及 PENPOT_BASE_URL 到 http://localhost:9001.

运行测试

uv sync --group dev
uv run pytest tests/ -v

项目结构

penpot-mcp-server/
├── src/penpot_mcp/
│   ├── server.py            # FastMCP entry point, 68 tool registrations, plugin routes
│   ├── config.py            # Pydantic Settings configuration
│   ├── gateway.py           # Hybrid context gateway (DB + Plugin awareness)
│   ├── ws_controller.py     # WebSocket server for browser plugin bridge (:4402)
│   ├── plugin/
│   │   ├── manifest.json    # Penpot plugin manifest (served at /plugin/manifest.json)
│   │   ├── plugin.js        # Plugin worker — penpot.* API only (no WebSocket in sandbox)
│   │   └── ui.html          # Plugin iframe — WebSocket lives here, relays to plugin.js
│   ├── services/
│   │   ├── db.py            # asyncpg connection pool
│   │   ├── api.py           # httpx RPC API client
│   │   ├── changes.py       # Penpot change operations builder
│   │   └── transit.py       # Transit+JSON decoder
│   ├── tools/
│   │   ├── projects.py      # Team & project queries
│   │   ├── files.py         # File CRUD operations
│   │   ├── shapes.py        # Shape reading & search
│   │   ├── create.py        # Shape creation
│   │   ├── modify.py        # Shape modification
│   │   ├── text.py          # Text operations
│   │   ├── export.py        # PNG/SVG export
│   │   ├── components.py    # Components & design tokens
│   │   ├── comments.py      # Comments & collaboration
│   │   ├── media.py         # Media assets & fonts
│   │   ├── database.py      # Raw SQL queries
│   │   └── advanced.py      # File raw data & revision comparison
│   └── transformers/
│       ├── css.py           # Shape → CSS conversion
│       ├── svg.py           # Shape → SVG conversion
│       └── layout.py        # Layout → CSS flexbox/grid
├── tests/
│   ├── conftest.py
│   ├── test_projects.py
│   ├── test_files.py
│   ├── test_shapes.py
│   └── test_e2e_login_form.py
├── pyproject.toml
├── Dockerfile
├── .env.example
├── setup.sh
├── docker-compose.penpot.yml
├── TOOLS.md
└── LICENSE

______________________________________________________________________

许可证

该项目根据 Apache许可证2.0.

______________________________________________________________________

致谢

• 佩普特 --开源设计平台
• 模型上下文协议 --协议标准
• FastMCP --Python MCP SDK

⬆ 返回页首