Penpot Mcp

Penpot MCP 🎨🤖

AI 驱动的设计工作流自动化
通过 Model Context Protocol 将 Claude AI 和其他大模型连接到 Penpot 设计

---

🚀 什么是 Penpot MCP？

Penpot MCP 是一款开创性的 Model Context Protocol（MCP）服务，搭建起 AI 大模型与 Penpot 之间的桥梁。Penpot 是一个开源设计与原型平台。此集成让 Claude 等 AI 助手（包括 Claude Desktop 和 Cursor IDE）能够以编程方式理解、分析和操作你的设计文件。

🎯 主要优势

• 🤖 原生 AI 设计分析：让 Claude AI 分析你的 UI/UX 设计、提供反馈并提出改进建议
• ⚡ 自动化设计工作流：借助 AI 驱动的自动化，简化重复性设计任务
• 🔍 智能设计搜索：使用自然语言在项目中查找设计组件和模式
• 📊 设计系统管理：借助 AI 助手自动记录和维护设计系统
• 🎨 跨平台集成：适用于任何兼容 MCP 的 AI 助手（Claude Desktop、Cursor IDE 等）

🎥 演示视频

观看演示视频，了解 Penpot MCP 的实际运行效果：

✨ 功能特性

🔌 核心能力

• MCP 协议实现：完全符合 Model Context Protocol 标准
• 实时设计访问：直接集成 Penpot 的 API，获取实时设计数据
• 组件分析：由 AI 驱动的设计组件和布局分析
• 导出自动化：以编程方式将设计资源导出为多种格式
• 设计验证：自动检查是否符合设计系统规范

🛠️ 开发者工具

• 命令行实用工具：强大的 CLI 工具，用于设计文件分析和验证
• Python SDK：全面的 Python 库，支持自定义集成
• REST API：用于 Web 应用集成的 HTTP 端点
• 可扩展架构：用于自定义 AI 工作流的插件系统

🎨 AI 集成功能

• Claude Desktop 和 Cursor 集成：原生支持 Claude Desktop 和 Cursor IDE 中的 Claude AI 助手
• 设计上下文共享：向 AI 模型提供设计上下文，以获得更好的回答
• 视觉组件识别：AI 可以“看到”并理解设计组件
• 自然语言查询：用日常语言询问有关设计的问题
• IDE 集成：与现代开发环境无缝集成

💡 使用场景

面向设计师

• 设计评审自动化：即时获取 AI 对无障碍性、易用性和设计原则的反馈
• 组件文档：自动为设计系统生成文档
• 设计一致性检查：确保各项目符合品牌指南
• 资源整理：借助 AI 对设计组件进行标记和分类

面向开发者

• 设计到代码工作流：借助 AI 助手弥合设计与开发之间的差距
• API 集成：以编程方式访问设计数据，用于自定义工具和工作流
• 自动化测试：根据设计规范生成视觉回归测试
• 设计系统同步：保持设计令牌与代码组件同步

面向产品团队

• 设计分析：跟踪设计系统的采用情况和组件使用情况
• 增强协作：借助 AI 实现设计评审和反馈收集
• 工作流优化：自动执行重复的设计操作和审批
• 跨工具集成：将 Penpot 与设计工作流中的其他工具连接起来

🚀 快速开始

前提条件

• Python 3.12+（建议使用最新版本的 Python，以获得最佳性能）
• Penpot 账号（免费注册）
• Claude Desktop 或 Cursor IDE（可选，用于 AI 集成）

安装

前提条件

• Python 3.12+
• Penpot 账号凭据

安装

选项 1：从 PyPI 安装

pip install penpot-mcp

选项 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 .

配置

根据 env.example 创建 .env 文件，并填入你的 Penpot 凭据：

PENPOT_API_URL=https://design.penpot.app/api
PENPOT_USERNAME=your_penpot_username
PENPOT_PASSWORD=your_penpot_password
PORT=5000
DEBUG=true

⚠️ CloudFlare 防护提示：Penpot 云站点（penpot.app）使用 CloudFlare 防护，偶尔可能会阻止 API 请求。如果遇到身份验证错误或请求被阻止：

1. 打开浏览器并访问 https://design.penpot.app
2. 登录你的 Penpot 账号
3. 按提示完成任何 CloudFlare 人机验证
4. 验证完成后，API 请求在一段时间内应可正常工作

使用方法

运行 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 服务，可以：

1. 在 .env 文件中设置 DEBUG=true 以启用调试模式
2. 使用 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 文件中的对象

AI 集成

Penpot MCP 服务可通过 Model Context Protocol 与 AI 助手集成。它支持 Claude Desktop 和 Cursor IDE，可无缝实现设计工作流自动化。

Claude Desktop 集成

有关 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：

1. 安装 MCP 服务（如果尚未安装）：

   pip install penpot-mcp
   

2. 配置 Cursor 设置，将 MCP 服务添加到 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"
         }
       }
     }
   }
   

3. 替代方案：使用环境变量，在项目根目录中创建 .env 文件：

   PENPOT_API_URL=https://design.penpot.app/api
   PENPOT_USERNAME=your_penpot_username
   PENPOT_PASSWORD=your_penpot_password
   

4. 启动 MCP 服务，在项目中运行：

   # In your project directory
   penpot-mcp
   

5. 在 Cursor 中使用：配置完成后，你可以直接在 Cursor 中与 Penpot 设计交互，例如提出以下问题：

   • “显示我 Penpot 账户中的所有项目”
   • “分析项目 X 中的设计组件”
   • “将主按钮组件导出为图片”
   • “此文件中使用了哪些设计模式？”

主要集成功能

Claude Desktop 和 Cursor 集成均提供：

• 直接访问 Penpot 项目和文件
• 可视化组件分析，并提供 AI 驱动的洞察
• 设计导出功能，可导出资源和组件
• 关于设计文件的自然语言查询
• 实时设计反馈和建议
• 设计系统文档生成

包结构

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 Request。

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add some amazing feature'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 发起 Pull Request

请确保代码遵循项目的编码规范，并包含适当的测试。

许可证

此项目采用 MIT License 许可，详情请参阅 LICENSE 文件。

致谢

• Penpot - 开源设计与原型制作平台
• Model Context Protocol - 用于 AI 模型上下文的标准化协议