绘图板-MCP服务器

作者：zcube1 星标更新：2025-11-07

安装使用来源：spider==github.com

项目介绍

Penpot MCP Server

这是一个模型上下文协议（MCP）服务器，提供了Penpot（开源设计工具）的完全操作能力。该服务器使AI助手能够通过编程方式创建、修改和管理Penpot设计，类似于Figma插件的功能。

🐳 支持多架构Docker镜像： linux/amd64, linux/arm64

🎬 实际演示

聊天界面示例

通过与使用此MCP服务器的AI助手进行自然对话完全创建的聊天界面示例。请参阅示例7：聊天界面，了解生成此设计的完整对话。

上图展示了如何用自然语言描述一个设计，AI助手将使用MCP服务器的能力在Penpot中创建它——自动处理布局、样式、组件和交互。

功能

🎨 完整的设计操作

创建及管理文件：创建新的设计文件，列出项目，管理文件元数据
形状操作：创建矩形、圆形、框架、路径、文本和SVG形状
修改设计：更新形状属性，移动对象，调整大小，旋转和样式
页面管理：添加、删除并组织文件中的页面
组件系统：创建和管理可重用组件

🔄 实时操作

直接与Penpot集成的API
基于会话的更新，带有修订跟踪
批量操作支持

🛠️ 可用工具（76+工具！）

项目及文件管理（8个工具）

list_teams - 列出所有可访问的团队
list_projects - 列出所有可访问的项目
list_files - 列出项目中的文件
get_file - 获取文件数据和结构
create_file - 创建新的设计文件
rename_file - 重命名现有文件
delete_file - 永久删除文件

页面管理（8个工具）

list_pages - 列出文件中的所有页面
add_page - 向文件中添加新页面
get_page_shapes - 获取特定页面上的所有形状（基本信息）
query_shapes - 根据条件查询和过滤形状（如grep）。按类型、区域、颜色、字体、文本内容筛选。选择要返回的字段。适用于批量操作
get_shape_properties - 获取特定形状的详细属性（颜色、文本、字体、效果等）
rename_page - 重命名页面
delete_page - 从文件中删除页面
move_shapes - 将形状移动到不同的父级/框架或重新排序

形状创建（6个工具）

create_rectangle - 创建矩形形状
create_circle - 创建圆形/椭圆形状
create_frame - 创建框架容器
create_text - 创建具有对齐方式（左、中、右、两端对齐）、字体和样式的文本元素
create_svg - 创建SVG元素
create_path - 创建自定义路径（计划中）

形状操作（3个工具）

update_shape - 修改形状属性（位置、大小、样式等）
delete_shape - 从设计中移除形状
duplicate_shapes - 复制形状（计划中）
group_shapes - 组合多个形状（计划中）

形状对齐与分布（2个工具）

align_shapes - 对齐多个形状（左、中、右、顶、中、底）
distribute_shapes - 均匀分布形状，间距相等（水平、垂直）

组件系统（5个工具）

create_component - 从形状创建可重用组件
update_component - 更新组件名称/路径
delete_component - 从库中删除组件
list_components - 列出文件中的所有组件
instantiate_component - 创建组件实例（计划中）

团队及协作（10个工具）

create_team - 创建新团队
update_team - 更新团队设置
delete_team - 删除团队
list_team_members - 列出团队的所有成员
invite_team_member - 邀请用户加入团队
remove_team_member - 从团队中移除成员
update_team_member_role - 更新成员权限
create_project - 在团队中创建新项目
update_project - 更新项目设置
delete_project - 删除项目

文件共享（3个工具）

create_share_link - 为文件创建可分享链接
list_share_links - 列出文件的所有分享链接
delete_share_link - 删除分享链接

评论及反馈（8个工具）

list_comment_threads - 列出文件中的评论线程
get_comments - 获取线程中的所有评论
create_comment_thread - 创建新的评论线程
add_comment - 向现有线程添加评论
update_comment - 更新现有评论
delete_comment - 删除评论
delete_comment_thread - 删除整个线程
update_comment_thread_status - 标记线程为已解决/未解决

导出及媒体（5个工具）

export_shape - 将形状/框架导出为图像（PNG、JPG、SVG、PDF）
list_file_media - 列出文件中使用的所有媒体
upload_file_media - 上传图像文件（PNG、JPG、SVG、GIF、WEBP）
upload_file_media_from_url - 从URL上传图像
delete_file_media - 删除媒体对象
clone_media - 从另一个文件克隆媒体

字体管理（5个工具）

upload_font - 上传自定义字体（TTF、OTF、WOFF、WOFF2）
list_team_fonts - 列出团队中的所有字体
get_font_variants - 获取字体家族的所有变体
update_font_variant - 更新字体元数据
delete_font_variant - 删除字体变体

Webhooks（5个工具）

create_webhook - 为事件通知创建webhook
list_webhooks - 列出团队中的所有webhook
update_webhook - 更新webhook设置
delete_webhook - 删除webhook
get_webhook_events - 获取关于webhook事件类型的详细信息

搜索（5个工具）

search_files - 按名称搜索文件
search_projects - 按名称搜索项目
search_shapes - 在文件内搜索形状
search_components - 按名称搜索组件
advanced_search - 跨多种资源类型搜索

配置文件及统计（5个工具）

get_profile - 获取当前用户配置文件
update_profile - 更新用户配置文件设置
list_recent_files - 列出最近访问的文件
get_file_permissions - 获取文件权限
get_team_stats - 获取团队统计数据

安装

方案1：使用npm（推荐用于CLI）

全局安装：

# 全局安装
npm install -g @zcubekr/penpot-mcp-server

# 运行服务器
penpot-mcp-server

# 或者以HTTP模式运行
TRANSPORT=http penpot-mcp-server

或者作为项目依赖安装：

# 作为依赖安装
npm install @zcubekr/penpot-mcp-server

# 使用npx运行
npx penpot-mcp-server

方案2：使用Docker（推荐用于HTTP服务器）

从GitHub容器注册表拉取预构建的多架构镜像：

# 拉取最新版本
docker pull ghcr.io/zcube/penpot-mcp-server:latest

# 或拉取特定版本
docker pull ghcr.io/zcube/penpot-mcp-server:v1.0.0

# 或拉取开发版本
docker pull ghcr
cr.io/zcube/penpot-mcp-server:main-dev

支持的架构：

linux/amd64 (x86_64)
linux/arm64 (ARM64/Apple Silicon)

方案3：从源代码构建

git clone https://github.com/zcube/penpot-mcp-server.git
cd penpot-mcp-server
npm install
npm run build

配置

设置您的Penpot凭据作为环境变量：

export PENPOT_API_URL="https://design.penpot.app"
export PENPOT_ACCESS_TOKEN="your-access-token-here"

或者创建一个.env文件（不建议用于生产环境）：

PENPOT_API_URL=https://design.penpot.app
PENPOT_ACCESS_TOKEN=your-access-token-here

获取Penpot访问令牌

登录到您的Penpot帐户
转到设置 → 访问令牌
创建一个新的访问令牌
复制并安全保存它

自托管Penpot服务器

如果您正在运行自托管的Penpot实例，则需要启用访问令牌支持：

重要提示： 由于公共Penpot实例上的Cloudflare安全限制，您可能需要使用自托管服务器来访问API。

启用访问令牌

在您的Penpot服务器配置中添加enable-access-tokens：

# docker-compose.yml 或 penpot-config.env
environment:
  - PENPOT_FLAGS=...enable-access-tokens

如果有其他标志，请将其追加到列表中：

# 示例：多个标志
environment:
  - PENPOT_FLAGS=enable-registration enable-login enable-access-tokens

启用此标志后，重启您的Penpot服务器，并可以从设置 → 访问令牌生成访问令牌。

使用方法

传输模式

此服务器支持两种传输模式：

stdio模式（默认） - 适用于本地MCP客户端，如Claude Desktop
HTTP/SSE模式 - 通过HTTP使用Server-Sent Events进行外部访问

stdio模式（默认）

与Claude Desktop一起使用

添加到您的Claude Desktop配置（macOS上的~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "penpot": {
      "command": "node",
      "args": ["/path/to/penpot-mcp-server/dist/index.js"],
      "env": {
        "PENPOT_API_URL": "https://design.penpot.app",
        "PENPOT_ACCESS_TOKEN": "your-access-token"
      }
    }
  }
}

与其他MCP客户端一起使用

node dist/index.js

HTTP/SSE模式（外部访问）

为了外部访问，您可以使用HTTP模式和Server-Sent Events运行服务器：

快速开始使用Docker

# 使用Docker运行
docker run -d \
  --name penpot-mcp-server \
  -p 3000:3000 \
  -e TRANSPORT=http \
  -e PENPOT_API_URL=https://design.penpot.app \
  -e PENPOT_ACCESS_TOKEN=your-access-token \
  ghcr.io/zcube/penpot-mcp-server:latest

# 使用自定义端口和自托管Penpot
docker run -d \
  --name penpot-mcp-server \
  -p 8080:8080 \
  -e TRANSPORT=http \
  -e HTTP_PORT=8080 \
  -e PENPOT_API_URL=https://penpot.mycompany.com \
  -e PENPOT_ACCESS_TOKEN=
your-access-token \
  ghcr.io/zcube/penpot-mcp-server:latest

# 查看日志
docker logs -f penpot-mcp-server

# 停止服务器
docker stop penpot-mcp-server
docker rm penpot-mcp-server

快速开始使用Node.js

# 使用npm脚本
npm run dev:http

# 或使用环境变量
TRANSPORT=http node dist/index.js

# 使用自定义端口
TRANSPORT=http HTTP_PORT=8080 node dist/index.js

配置选项

# 必需
export PENPOT_ACCESS_TOKEN="your-access-token"

# 可选
export PENPOT_API_URL="https://design.penpot.app"  # 默认值
export HTTP_PORT="3000"                             # 默认值
export HTTP_HOST="0.0.0.0"                          # 默认值

# 安全选项
export ALLOWED_ORIGINS="https://example.com,https://app.example.com"
export ALLOWED_HOSTS="localhost,example.com"
export ENABLE_DNS_REBINDING_PROTECTION="true"

HTTP端点

一旦运行，服务器将暴露：

MCP端点：http://localhost:3000/mcp
- GET：建立SSE流以接收消息
- POST：向服务器发送JSON-RPC消息
- DELETE：关闭会话并清理
健康检查：http://localhost:3000/health
- 返回服务器状态和活动会话计数

示例HTTP客户端使用

// 初始化连接（GET请求）
const eventSource = new EventSource('http://localhost:3000/mcp');

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('收到：', data);
};

// 发送消息（POST请求）
fetch('http://localhost:3000/mcp', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'mcp-session-id': sessionId, // 从SSE端点响应获取
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'tools/list',
  }),
});

使用Docker的HTTP模式

# 使用docker-compose
docker compose up -d

# 或使用docker run
docker run -d \
  -e TRANSPORT=http \
  -e HTTP_PORT=3000 \
  -e PENPOT_ACCESS_TOKEN=your-token \
  -p 3000:3000 \
  penpot-mcp-server:latest

安全注意事项

当以HTTP模式运行时：

生产中使用HTTPS - 在反向代理（如nginx、Caddy等）后面运行
启用CORS限制 - 使用ALLOWED_ORIGINS限制访问
启用DNS重绑定保护 - 设置ENABLE_DNS_REBINDING_PROTECTION=true
防火墙规则 - 限制访问可信网络
令牌安全 - 保持访问令牌的安全性，定期轮换

示例用法

一旦连接，您可以要求您的AI助手：

"为移动应用登录页面创建一个新的设计文件"
"在位置100,100处添加一个红色填充的矩形"
"创建一个名为'Hero Section'的框架并在其中添加一些文本"
"列出当前页面上的所有形状"
"将矩形移动到位置200,200并调整其大小为300x200"
"创建一个蓝色描边且无填充的圆形"

API架构

此服务器使用Penpot的RPC API，其结构如下：

端点：https://design.penpot.app/api/rpc/command/<method-name>
认证：通过Authorization: Token <token>传递Bearer令牌
Content-Type：application/json或application/transit+json

测试

✅ 自动化CI/CD测试

每次推送和拉取请求都会自动运行所有测试！

GitHub Actions工作流程：

🧪 运行全面的测试套件（45个测试覆盖76+工具）
✅ 使用penpot-test环境针对外部Penpot实例进行测试
🐳 构建并验证Docker镜像（多架构）
📊 上传测试结果作为工件

工作流程：.github/workflows/docker.yml → integration-test任务

使用外部Penpot实例测试

您还可以针对真实的Penpot实例进行测试：

在https://design.penpot.app创建Penpot帐户
在设置 → 访问令牌中生成访问令牌
设置环境变量：

export PENPOT_API_URL="https://design.penpot.app"
export PENPOT_ACCESS_TOKEN="your-token-here"

运行测试：

# 运行完整的测试套件
npm test

# 或使用npx运行
npx tsx test-tools.ts

测试套件将：

✅ 测试所有70+ MCP工具
✅ 创建包含形状的测试文件
✅ 测试组件、评论、共享
✅ 搜索功能
✅ 验证所有操作

详见TESTING.md中的详细测试指南。

Docker

快速开始使用Docker

# 创建.env文件
echo "PENPOT_API_URL=https://design.penpot.app" > .env
echo "PENPOT_ACCESS_TOKEN=your-token" >> .env

# 使用Docker Compose运行
docker compose up -d

# 查看日志
docker compose logs -f

# 运行测试
docker compose --profile test up penpot-mcp-test