Penpot MCP 服务器🎨🤖
🚀 Penpot MCP 是什么？
Penpot MCP是一款革命性的模型上下文协议 (MCP) 服务器，它弥合了 AI 语言模型与开源设计和原型设计平台Penpot之间的鸿沟。这种集成使 Claude 等 AI 助手（在 Claude Desktop 和 Cursor IDE 中）能够以编程方式理解、分析和与您的设计文件交互。
🎯 主要优点
- 🤖 AI 原生设计分析：让 Claude AI 分析您的 UI/UX 设计，提供反馈并提出改进建议
- ⚡ 自动化设计工作流程：利用人工智能自动化简化重复的设计任务
- 🔍 智能设计搜索：使用自然语言查找项目中的设计组件和模式
- 📊 设计系统管理：借助 AI 帮助自动记录和维护设计系统
- 🎨 跨平台集成：可与任何与 MCP 兼容的 AI 助手（Claude Desktop、Cursor IDE 等）配合使用。
🎥 演示视频
观看我们的演示视频，了解 Penpot MCP 的实际运行情况：
✨ 特点
🔌 核心能力
- MCP协议实现：完全符合模型上下文协议标准
- 实时设计访问：与 Penpot 的 API 直接集成以获取实时设计数据
- 组件分析：人工智能驱动的设计组件和布局分析
- 导出自动化：以多种格式编程导出设计资产
- 设计验证：自动化设计系统合规性检查
🛠️ 开发者工具
- 命令行实用程序：用于设计文件分析和验证的强大 CLI 工具
- Python SDK ：用于自定义集成的综合 Python 库
- REST API ：用于 Web 应用程序集成的 HTTP 端点
- 可扩展架构：用于自定义 AI 工作流程的插件系统
🎨 AI 集成功能
- Claude Desktop 和 Cursor 集成：Claude Desktop 和 Cursor IDE 均原生支持 Claude AI 助手
- 设计上下文共享：向 AI 模型提供设计上下文，以获得更好的响应
- 视觉组件识别：人工智能可以“看到”并理解设计组件
- 自然语言查询：用简单的英语询问有关您的设计的问题
- IDE 集成：与现代开发环境无缝集成
💡 用例
对于设计师
- 设计审查自动化：获取有关可访问性、可用性和设计原则的即时 AI 反馈
- 组件文档：自动生成设计系统文档
- 设计一致性检查：确保整个项目符合品牌指南
- 资产组织：人工智能驱动的设计组件标记和分类
对于开发人员
- 设计到代码工作流程：借助人工智能弥合设计与开发之间的差距
- API 集成：通过编程访问自定义工具和工作流程的设计数据
- 自动化测试：根据设计规范生成可视化回归测试
- 设计系统同步：保持设计令牌和代码组件同步
对于产品团队
- 设计分析：跟踪设计系统的采用和组件的使用情况
- 协作增强：人工智能驱动的设计评审和反馈收集
- 工作流程优化：自动化重复的设计操作和审批
- 跨工具集成：将 Penpot 与设计工作流程中的其他工具连接起来
🚀 快速入门
先决条件
- Python 3.12+ （建议使用最新 Python 以获得最佳性能）
- Penpot 账户（免费注册）
- Claude Desktop 或 Cursor IDE （可选，用于 AI 集成）
安装
先决条件
安装
选项 1：从 PyPI 安装
选项 2：使用 uv（推荐用于现代 Python 开发）
# Install directly with uvx (when published to PyPI)
uvx penpot-mcp
# For local development, use uvx with local path
uvx --from . penpot-mcp
# Or install in a project with uv
uv add penpot-mcp
选项 3：从源安装
# Clone the repository
git clone https://github.com/montevive/penpot-mcp.git
cd penpot-mcp
# Using uv (recommended)
uv sync
uv run penpot-mcp
# Or using traditional pip
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
pip install -e .
配置
使用您的 Penpot 凭证根据env.example创建.env文件：
PENPOT_API_URL=https://design.penpot.app/api
PENPOT_USERNAME=your_penpot_username
PENPOT_PASSWORD=your_penpot_password
PORT=5000
DEBUG=true
用法
运行 MCP 服务器
# Using uvx (when published to PyPI)
uvx penpot-mcp
# Using uvx for local development
uvx --from . penpot-mcp
# Using uv in a project (recommended for local development)
uv run penpot-mcp
# Using the entry point (if installed)
penpot-mcp
# Or using the module directly
python -m penpot_mcp.server.mcp_server
调试 MCP 服务器
要调试 MCP 服务器，您可以：
- 通过设置
DEBUG=true在.env文件中启用调试模式 - 使用 Penpot API CLI 测试 API 操作：
# Test API connection with debug output
python -m penpot_mcp.api.penpot_api --debug list-projects
# Get details for a specific project
python -m penpot_mcp.api.penpot_api --debug get-project --id YOUR_PROJECT_ID
# List files in a project
python -m penpot_mcp.api.penpot_api --debug list-files --project-id YOUR_PROJECT_ID
# Get file details
python -m penpot_mcp.api.penpot_api --debug get-file --file-id YOUR_FILE_ID
命令行工具
该软件包包括实用命令行工具：
# Generate a tree visualization of a Penpot file
penpot-tree path/to/penpot_file.json
# Validate a Penpot file against the schema
penpot-validate path/to/penpot_file.json
MCP 监控与测试
MCP CLI 监视器
# Start your MCP server in one terminal
python -m penpot_mcp.server.mcp_server
# In another terminal, use mcp-cli to monitor and interact with your server
python -m mcp.cli monitor python -m penpot_mcp.server.mcp_server
# Or connect to an already running server on a specific port
python -m mcp.cli monitor --port 5000
MCP 检查器
# Start your MCP server in one terminal
python -m penpot_mcp.server.mcp_server
# In another terminal, run the MCP Inspector (requires Node.js)
npx @modelcontextprotocol/inspector
使用客户端
# Run the example client
penpot-client
MCP 资源和工具
资源
server://info - 服务器状态和信息penpot://schema - JSON 格式的 Penpot API 架构penpot://tree-schema - JSON 格式的 Penpot 对象树模式rendered-component://{component_id} - 渲染的组件图像penpot://cached-files - 缓存的 Penpot 文件列表
工具
list_projects - 列出所有 Penpot 项目get_project_files - 获取特定项目的文件get_file - 通过 ID 检索 Penpot 文件并缓存它export_object - 将 Penpot 对象导出为图像get_object_tree - 获取 Penpot 对象的对象树结构search_object - 按名称搜索 Penpot 文件中的对象
人工智能集成
Penpot MCP 服务器可以使用模型上下文协议 (MCP) 与 AI 助手集成。它支持 Claude Desktop 和 Cursor IDE，实现无缝设计工作流程自动化。
Claude 桌面集成
有关 Claude Desktop 设置的详细信息，请参阅CLAUDE_INTEGRATION.md 。
将以下配置添加到您的 Claude Desktop 配置文件（macOS 上为~/Library/Application Support/Claude/claude_desktop_config.json或 Windows 上为%APPDATA%\Claude\claude_desktop_config.json ）：
{
"mcpServers": {
"penpot": {
"command": "uvx",
"args": ["penpot-mcp"],
"env": {
"PENPOT_API_URL": "https://design.penpot.app/api",
"PENPOT_USERNAME": "your_penpot_username",
"PENPOT_PASSWORD": "your_penpot_password"
}
}
}
}
Cursor IDE 集成
Cursor IDE 通过其 AI 集成功能支持 MCP 服务器。要使用 Cursor 配置 Penpot MCP，请执行以下操作：
- 安装 MCP 服务器（如果尚未安装）：
- 通过将 MCP 服务器添加到 Cursor 配置来配置 Cursor 设置。打开 Cursor 设置并添加：
{
"mcpServers": {
"penpot": {
"command": "uvx",
"args": ["penpot-mcp"],
"env": {
"PENPOT_API_URL": "https://design.penpot.app/api",
"PENPOT_USERNAME": "your_penpot_username",
"PENPOT_PASSWORD": "your_penpot_password"
}
}
}
}
- 替代方案：通过在项目根目录中创建
.env文件来使用环境变量：PENPOT_API_URL=https://design.penpot.app/api
PENPOT_USERNAME=your_penpot_username
PENPOT_PASSWORD=your_penpot_password
- 在您的项目中启动 MCP 服务器：
# In your project directory
penpot-mcp
- 在 Cursor 中使用：配置完成后，您可以通过询问以下问题直接在 Cursor 中与您的 Penpot 设计进行交互：
- “显示我的 Penpot 帐户中的所有项目”
- “分析项目X中的设计组件”
- “将主按钮组件导出为图像”
- “该文件使用了哪些设计模式？”
主要集成功能
Claude Desktop 和 Cursor 集成均提供：
- 直接访问Penpot 项目和文件
- 利用人工智能洞察进行可视化组件分析
- 资产和组件的设计导出功能
- 关于您的设计文件的自然语言查询
- 实时设计反馈和建议
- 设计系统文档生成
包结构
penpot_mcp/
├── api/ # Penpot API client
├── server/ # MCP server implementation
│ ├── mcp_server.py # Main MCP server
│ └── client.py # Client implementation
├── tools/ # Utility tools
│ ├── cli/ # Command-line interfaces
│ └── penpot_tree.py # Penpot object tree visualization
├── resources/ # Resource files and schemas
└── utils/ # Helper utilities
发展
测试
项目采用pytest进行测试：
# Using uv (recommended)
uv sync --extra dev
uv run pytest
# Run with coverage
uv run pytest --cov=penpot_mcp tests/
# Using traditional pip
pip install -e ".[dev]"
pytest
pytest --cov=penpot_mcp tests/
代码检查
# Using uv (recommended)
uv sync --extra dev
# Set up pre-commit hooks
uv run pre-commit install
# Run linting
uv run python lint.py
# Auto-fix linting issues
uv run python lint.py --autofix
# Using traditional pip
pip install -r requirements-dev.txt
pre-commit install
./lint.py
./lint.py --autofix
贡献
欢迎贡献代码！欢迎提交 Pull 请求。
- 分叉存储库
- 创建你的功能分支（
git checkout -b feature/amazing-feature ） - 提交您的更改（
git commit -m 'Add some amazing feature' ） - 推送到分支（
git push origin feature/amazing-feature ） - 打开拉取请求
请确保您的代码遵循项目的编码标准并包含适当的测试。
执照
该项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅LICENSE文件。
致谢