Penpot MCP Server

Penpot MCP服务器🎨🤖

AI-Powered Design Workflow Automation

Connect Claude AI and other LLMs to Penpot designs via Model Context Protocol

______________________________________________________________________

🚀 什么是Penpot MCP？

笔筒MCP 是一个革命性的模型上下文协议（MCP）服务器，弥合了人工智能语言模型和 佩普特开源设计和原型平台。这种集成使像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库
• REST API：用于web应用程序集成的HTTP端点
• 可扩展架构：用于自定义AI工作流的插件系统

🎨 AI集成功能

• Claude桌面和光标集成：在Claude Desktop和Cursor IDE中原生支持Claude AI助手
• 设计上下文共享：为人工智能模型提供设计背景，以获得更好的响应
• 视觉组件识别：AI可以“看到”和理解设计组件
• 自然语言查询：用简单的英语问你的设计问题
• IDE集成：与现代开发环境无缝集成

💡 用例

对于设计师

• 设计评审自动化：获取关于可访问性、可用性和设计原则的即时AI反馈
• 组件文档：自动生成设计系统的文档
• 设计一致性检查：确保所有项目都符合品牌指南
• 资产组织：设计组件的人工智能标记和分类

对于开发者

• 从设计到代码的工作流：在人工智能的帮助下弥合设计和开发之间的差距
• API集成：通过编程访问自定义工具和工作流的设计数据
• 自动化测试：根据设计规范生成视觉回归测试
• 设计系统同步：保持设计令牌和代码组件同步

产品团队

• 设计分析：轨道设计系统采用和组件使用
• 协作增强：人工智能驱动的设计审查和反馈收集
• 工作流程优化：自动化重复的设计操作和审批
• 跨工具集成：将Penpot与设计工作流程中的其他工具连接起来

🚀 快速开始

先决条件

• Python 3.12+ （建议使用最新Python以获得最佳性能）
• Penpot帐户 (免费注册)
• Claude桌面或光标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 文件基于 env.example 使用您的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 1. 登录您的Penpot帐户 1. 如有提示，完成任何CloudFlare人工验证挑战 1. 一旦得到验证，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 -Penpot API模式为JSON
• penpot://tree-schema -JSON格式的Penpot对象树模式
• rendered-component://{component_id} -渲染的组件图像
• penpot://cached-files -缓存的Penpot文件列表

工具

• list_projects -列出所有Penpot项目
• get_project_files -获取特定项目的文件
• get_file -根据Penpot文件的ID检索并缓存它
• export_object -将Penpot对象导出为图像
• get_object_tree -获取Penpot对象的对象树结构
• search_object -按名称搜索Penpot文件中的对象

人工智能集成

Penpot MCP服务器可以使用模型上下文协议与AI助手集成。它支持Claude Desktop和Cursor IDE，实现无缝的设计工作流自动化。

Claude桌面集成

有关详细的Claude Desktop设置说明，请参阅 CLAUDE_集成.md.

将以下配置添加到Claude Desktop配置文件中(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS或 %APPDATA%\Claude\claude_desktop_config.json 在Windows上）：

{
  "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"
      }
    }
  }
}

游标IDE集成

Cursor IDE通过其AI集成功能支持MCP服务器。要使用光标配置Penpot MCP：

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

   pip install penpot-mcp

1. 配置光标设置 通过将MCP服务器添加到游标配置中。打开光标设置并添加：

   {
     "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"
         }
       }
     }
   }

1. 替代方案：使用环境变量 通过创建a .env 项目根目录中的文件：

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

1. 启动MCP服务器 在您的项目中：

   # In your project directory
   penpot-mcp

1. 在游标中使用：配置后，您可以通过提出以下问题直接在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

贡献

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

1. 复刻仓库
2. 创建功能分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add some amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

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

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

致谢

• 佩普特 -开源设计和原型制作平台
• 模型上下文协议 -人工智能模型上下文的标准化协议