Penpot Mcp

Penpot MCP サーバー 🎨🤖

AI を活用したデザインワークフローの自動化
Model Context Protocol を介して Claude AI やその他の LLM を Penpot のデザインに接続します

---

🚀 Penpot MCP とは？

Penpot MCP は、AI 言語モデルと、オープンソースのデザイン・プロトタイピングプラットフォームである Penpot をつなぐ、革新的な Model Context Protocol（MCP）サーバーです。この連携により、Claude（Claude Desktop と Cursor IDE の両方で）などの AI アシスタントが、デザインファイルをプログラムから理解、分析、操作できるようになります。

🎯 主なメリット

• 🤖 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 .

設定

Penpot の認証情報を記入した .env ファイルを env.example を基に作成します。

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. Web ブラウザーを開き、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 Inspector

# 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 - Penpot オブジェクトツリースキーマ（JSON 形式）
• 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 の設定を構成するには、Cursor の設定に MCP サーバーを追加します。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

コントリビューション

コントリビューションを歓迎します。お気軽にプルリクエストを送信してください。

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 License の下でライセンスされています。詳細については、LICENSE ファイルを参照してください。

謝辞

• Penpot - オープンソースのデザインおよびプロトタイピングプラットフォーム
• Model Context Protocol - AI モデルのコンテキストに関する標準化プロトコル