使用说明

Penpot MCP服务器

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

🐳 多架构Docker镜像可用： linux/amd64, linux/arm64

🎬 在行动中看到它

示例聊天界面完全通过使用此MCP服务器与AI助手的自然对话创建。看示例7：聊天界面对于生成此设计的完整对话。

上面的屏幕截图演示了如何用自然语言描述设计，人工智能助手将使用MCP服务器的功能在Penpot中创建它——自动处理布局、样式、组件和交互。

特性

🎨 完整的设计操作

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

🔄 实时操作

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

🛠️ 可用工具（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 -列出团队的所有webhooks
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 globally
npm install -g @zcubekr/penpot-mcp-server

# Run the server
penpot-mcp-server

# Or run in HTTP mode
TRANSPORT=http penpot-mcp-server

或者作为项目依赖项安装：

# Install as dependency
npm install @zcubekr/penpot-mcp-server

# Run via npx
npx penpot-mcp-server

选项2：使用Docker（推荐用于HTTP服务器）

从GitHub容器注册表中提取预构建的多架构映像：

# Pull latest version
docker pull ghcr.io/zcube/penpot-mcp-server:latest

# Or pull specific version
docker pull ghcr.io/zcube/penpot-mcp-server:v1.0.0

# Or pull development version
docker pull ghcr.io/zcube/penpot-mcp-server:main-dev

支持的体系结构：

linux/amd64 （x86_64）
linux/arm64 （ARM64/苹果硅）

选项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访问。

启用访问令牌

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

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

如果您有其他标志，请附加 enable-access-tokens 到列表：

# Example with multiple flags
environment:
  - PENPOT_FLAGS=enable-registration enable-login enable-access-tokens

启用此标志后，重新启动Penpot服务器，您将能够从设置中生成访问令牌→ 访问令牌。

用法

运输方式

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

stdio模式（默认） -适用于Claude Desktop等本地MCP客户端
HTTP/SSE模式 -用于通过HTTP与服务器发送事件进行外部访问

标准模式（默认）

使用克劳德桌面

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

{
  "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模式下运行服务器：

Docker快速入门

# Run with 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

# With custom port and self-hosted 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

# View logs
docker logs -f penpot-mcp-server

# Stop server
docker stop penpot-mcp-server
docker rm penpot-mcp-server

Node.js快速入门

# Using npm script
npm run dev:http

# Or with environment variable
TRANSPORT=http node dist/index.js

# With custom port
TRANSPORT=http HTTP_PORT=8080 node dist/index.js

配置选项

# Required
export PENPOT_ACCESS_TOKEN="your-access-token"

# Optional
export PENPOT_API_URL="https://design.penpot.app"  # Default
export HTTP_PORT="3000"                             # Default
export HTTP_HOST="0.0.0.0"                          # Default

# Security options
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客户端使用示例

// Initialize connection (GET request)
const eventSource = new EventSource('http://localhost:3000/mcp');

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Received:', data);
};

// Send message (POST request)
fetch('http://localhost:3000/mcp', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'mcp-session-id': sessionId, // From SSE endpoint response
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'tools/list',
  }),
});

具有HTTP模式的Docker

# Using docker-compose
docker compose up -d

# Or with 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助手：

“为移动应用登录页创建新的设计文件”
“在位置100100处添加一个红色填充的矩形”
“创建一个名为“英雄部分”的框架，并在其中添加一些文本”
“列出当前页面上的所有形状”
“将矩形移动到位置200200，使其为300x200”
“创建一个蓝色笔划且无填充的圆”

API体系结构

此服务器使用Penpot的RPC API，具有以下结构：

端点: https://design.penpot.app/api/rpc/command/<method-name>
认证：持票人代币通过 Authorization: Token <token>
内容类型: application/json 或 application/transit+json

测试

✅ 自动化CI/CD测试

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

GitHub操作工作流：

🧪 运行全面的测试套件（45个测试，涵盖76多种工具）
✅ 使用Penpot测试环境对外部Penpot实例进行测试
🐳 构建和验证Docker镜像（multi-arch）
📊 将测试结果作为工件上传

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

使用外部Penpot实例进行测试

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

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

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

运行测试：

# Run full test suite
npm test

# Or run with npx
npx tsx test-tools.ts

测试套件将：

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

看测试.md 获取详细的测试指南。

码头工人

Docker快速入门

# Create .env file
echo "PENPOT_API_URL=https://design.penpot.app" > .env
echo "PENPOT_ACCESS_TOKEN=your-token" >> .env

# Run with Docker Compose
docker compose up -d

# View logs
docker compose logs -f

# Run tests
docker compose --profile test up penpot-mcp-test

构建Docker镜像

# Production image
docker build -t penpot-mcp-server:latest .

# Test image
docker build -f Dockerfile.test -t penpot-mcp-test:latest .

看医生.md 获取全面的Docker指南。

发展

# Watch mode for development
npm run watch

# Run in development
npm run dev

# Run tests during development
npm test

贡献

我们欢迎捐款！提交更改之前：

使用以下命令在本地测试GitHub操作游泳运动员/表演

# Install act
brew install act  # macOS
# or
curl -s https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash

# Test workflows before pushing
act -j build-and-test

# Test with larger runner image
act -P ubuntu-latest=catthehacker/ubuntu:act-latest

在本地测试Docker构建

docker build -t penpot-mcp-server:test .

使用本地Penpot容器运行测试

docker compose -f docker-compose.penpot.yml up -d
docker compose -f docker-compose.penpot.yml --profile test up penpot-mcp-test

看贡献.md 完整的开发指南，包括：

建立开发环境
使用act测试工作流
Docker构建测试
代码风格指南
拉取请求流程

Penpot API覆盖范围

此服务器实现了基于Penpot的25个RPC命令模块的工具：

模块	覆盖范围	工具
✅ files.clj	完整	创建文件、获取文件、列表文件、重命名文件、删除文件
✅ files_create.clj	完整	创建文件
✅ files_update.clj	完整	通过更新文件RPC进行所有形状/页面操作
✅ projects.clj	完整	列表_项目、创建_项目、更新_项目、删除_项目
✅ teams.clj	完整	列表_团队，创建_团队，更新_团队，删除_团队
✅ teams_invitations.clj	部分	邀请团队成员
✅ files_share.clj	完整	创建_share_link、列表_share_links、删除_share_lik
✅ comments.clj	完整	所有评论和线程操作
✅ media.clj	完整	上传_文件_媒体、列表_文件_介质、删除、克隆
✅ fonts.clj	完整	上传字体、列表、更新、删除字体变体
✅ webhooks.clj	完整	创建、列出、更新、删除webhooks
✅ search.clj	完整	搜索文件、项目、形状、组件
✅ profile.clj	部分	获取文件、更新文件、最近文件、权限
❌ auth.clj	N/A	通过访问令牌处理身份验证
❌ profile.clj	N/A	用户配置文件管理
❌ audit.clj	不适用	仅限管理员的审核日志
❌ viewer.clj	N/A	仅查看操作

传说: ✅ 已实施|⚠️ 部分/计划中|❌ 不适用于MCP用例

v1.0.0中的新功能-完整的API覆盖范围！ 🎉

1.0.0版本带来 全面实施 所有以前的部分功能：

✨ 媒体上传（完全实现）

文件上传：从本地文件系统上传图像
URL导入：直接从URL导入图像
格式支持：PNG、JPG、SVG、GIF、WEBP
管理：删除和克隆媒体对象
真正的多部分/表单数据上传支持

🔤 字体管理（全面实施）

上传字体：TTF、OTF、WOFF、WOFF2格式
字体族：每个团队管理多个字体系列
字体变体：多种重量和样式
团队字体：跨团队共享字体库

🔔 Webhooks（完全实现）

事件通知：file:已创建，file:已更新，comment:已创建等。
HTTPS端点：安全的webhook交付
管理：创建、更新、删除、列出Webhook
状态控制：启用/禁用webhooks

🔍 搜索（全面实施）

文件搜索：搜索所有项目
项目搜索：按名称查找项目
形状搜索：按名称/类型查找文件中的形状
组件搜索：在库中查找组件
高级搜索：多资源类型搜索

💬 增强评论（全面实施）

线程管理：创建、删除、解析线程
评论操作：添加、更新、删除评论
位置跟踪：与特定地点相关的评论
解决方案状态：将线程标记为已解决/未解决

👤 简介与统计（新增）

用户档案：获取和更新用户设置
最近的文件：访问历史跟踪
权限：检查文件访问级别
球队数据：项目、文件和成员计数

📈 覆盖范围摘要

19/25 RPC模块 已实施（覆盖率76%）
70+MCP工具 （从50+开始）
25+新工具 添加到v1.0.0中
Penpot的所有主要功能现在都可以通过AI访问

许可证

麻省理工学院

第三方代码和归因

OpenAPI规范

该项目使用Penpot OpenAPI规范 https://design.penpot.app/api/openapi.json.

这 openapi.json 该存储库中的文件是为了进行版本控制而维护的，以跟踪Penpot API随时间的变化。OpenAPI规范的版权仍归Penpot项目及其贡献者所有。

生成的代码

这 src/generated/ 目录包含使用Penpot OpenAPI规范自动生成的TypeScript客户端代码 @嘿，api/openapi ts （MIT许可证）。

API类型定义

中的类型定义 src/types.ts 基于Penpot的RPC API结构，并通过分析Penpot API响应和行为创建。

贡献

欢迎投稿！请随时提交拉取请求。

使用说明

Penpot MCP服务器

🎬 在行动中看到它

特性

🎨 完整的设计操作

🔄 实时操作

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

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

页面管理（8个工具）

形状创建（6个工具）

形状操纵（3个工具）

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

组件系统（5个工具）

团队与协作（10个工具）

文件共享（3个工具）

评论与反馈（8个工具）

导出和媒体（5个工具）

字体管理（5个工具）

Webhooks（5个工具）

搜索（5个工具）

配置文件和统计数据（5个工具）

安装

选项1：使用npm（建议用于CLI）

选项2：使用Docker（推荐用于HTTP服务器）

选项3：从源代码构建

配置

获取Penpot访问令牌

自托管Penpot服务器

启用访问令牌

用法

运输方式

标准模式（默认）

使用克劳德桌面

与其他MCP客户端

HTTP/SSE模式（外部访问）

Docker快速入门

Node.js快速入门

配置选项

HTTP端点

HTTP客户端使用示例

具有HTTP模式的Docker

安全考虑

示例用法

API体系结构

测试

✅ 自动化CI/CD测试

使用外部Penpot实例进行测试

码头工人

Docker快速入门

构建Docker镜像

发展

贡献

Penpot API覆盖范围

v1.0.0中的新功能-完整的API覆盖范围！ 🎉

✨ 媒体上传（完全实现）

🔤 字体管理（全面实施）

🔔 Webhooks（完全实现）

🔍 搜索（全面实施）

💬 增强评论（全面实施）

👤 简介与统计（新增）

📈 覆盖范围摘要

许可证

第三方代码和归因

OpenAPI规范

生成的代码

API类型定义

贡献

相关 MCP

小红书MCP服务

Figma MCP集成工具

MCP 协议测试服务器

Flomo笔记服务

Unity编辑器AI集成插件

科学研究的开源MCP服务器