psd-mcp

PSD ファイルからデザイン情報を抽出する MCP サーバーです。
Claude Code や Cursor などの AI コーディングツールから PSD デザインを直接読み取り、コード実装に活用できます。

Photoshop のインストールは不要です。 PSD ファイルを直接解析します。

---

目次

• できること
• 動作環境
• セットアップ
• MCP サーバーの設定
  • Claude Code
  • Cursor
  • Claude Desktop
• 動作確認
• ツール一覧
• 使い方ガイド
• PSD ファイルの準備（デザイナー向け）
• トラブルシューティング
• 技術スタック

---

できること

デザイナー                    開発者
  PSD ファイル ──────────→ Claude Code / Cursor
                              │
                              ├─ レイヤー構造の取得
                              ├─ テキスト・フォント情報の抽出
                              ├─ カラー・シャドウのデザイントークン化
                              ├─ スクリーンショット画像の取得
                              ├─ レイヤー単位の CSS 生成
                              ├─ レイアウト解析（flex方向・gap推定）
                              ├─ デザイン仕様書の自動生成
                              ├─ 実装とのピクセル差分比較
                              └─ そのまま React / HTML / CSS に実装

• PSD のレイヤー構造をツリー形式で確認
• テキストレイヤーのフォント名・サイズ・色・行間を一括抽出
• カラーパレット・フォント一覧・シャドウを CSS Variables / Tailwind / JSON で出力
• ドキュメント全体や個別レイヤーのスクリーンショットを PNG で取得
• レイヤーを PNG / JPEG でファイルに書き出し
• レイヤーのスタイルを CSS コードとして生成
• グループ内の レイアウト解析（flex方向、gap、整列パターン推定）
• 実装用の デザイン仕様書を再帰的に一括生成
• PSD デザインと実装スクリーンショットのピクセル差分比較
• 「この PSD を React コンポーネントにして」のような指示でコード生成

---

動作環境

項目	要件
Node.js	v18 以上 （v20 推奨）
npm	v9 以上
OS	macOS / Windows / Linux
AI ツール	Claude Code、Cursor、Claude Desktop のいずれか

---

セットアップ

1. リポジトリのクローン

git clone https://github.com/KimMaru10/psd-mcp.git
cd psd-mcp

2. 依存パッケージのインストール

npm install

macOS で canvas のインストールに失敗する場合：

brew install pkg-config cairo pango libpng jpeg giflib librsvg
npm install

Ubuntu / Debian の場合：

sudo apt-get install -y build-essential libcairo2-dev libpango1.0-dev libjpeg-dev libgif-dev librsvg2-dev
npm install

3. ビルド

npm run build

4. インストール先パスの確認

ビルド後、以下のパスをメモしておいてください。MCP 設定で使います。

# 自分の環境での絶対パスを確認
echo "$(pwd)/dist/index.js"

出力例: /Users/yourname/dev/psd-mcp/dist/index.js

---

MCP サーバーの設定

Claude Code

以下のコマンドで設定を追加します（最も簡単な方法）:

claude mcp add psd node /path/to/psd-mcp/dist/index.js

または、設定ファイルを直接編集する場合:

グローバル設定 (~/.claude/settings.json) ← 全プロジェクトで使える

{
  "mcpServers": {
    "psd": {
      "command": "node",
      "args": ["/path/to/psd-mcp/dist/index.js"]
    }
  }
}

プロジェクト設定 (.claude/settings.json) ← 特定プロジェクトのみ

{
  "mcpServers": {
    "psd": {
      "command": "node",
      "args": ["/path/to/psd-mcp/dist/index.js"]
    }
  }
}

/path/to/psd-mcp はセットアップ手順4で確認した実際のパスに置き換えてください。

---

Cursor

プロジェクトルートに .cursor/mcp.json を作成:

{
  "mcpServers": {
    "psd": {
      "command": "node",
      "args": ["/path/to/psd-mcp/dist/index.js"]
    }
  }
}

設定後、Cursor を再起動してください。

---

Claude Desktop

Settings > Developer > Edit Config を開き、以下を追加:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "psd": {
      "command": "node",
      "args": ["/path/to/psd-mcp/dist/index.js"]
    }
  }
}

設定後、Claude Desktop を再起動してください。

---

動作確認

設定後、以下の方法で正しく接続されているか確認できます。

Claude Code の場合

PSDファイルの分析ツールが使えますか？

と入力すると、get_document_info などのツールが利用可能であることを応答します。

実際のPSDで確認

/path/to/design.psd のドキュメント情報を表示して

レイヤーツリーとドキュメント情報が返ってくれば成功です。

---

ツール一覧

get_document_info - ドキュメント概要

PSD ファイル全体の構造を取得します。最初に呼ぶべきツールです。

パラメータ	型	必須	説明
filePath	string	○	PSD ファイルの絶対パス
includeScreenshot	boolean	-	合成画像のスクリーンショットを含めるか（デフォルト: true）

返却内容: ドキュメントサイズ、カラーモード、解像度、レイヤーツリー、スクリーンショット画像

---

get_layer_detail - レイヤー詳細

特定レイヤーの詳細情報を取得します。

パラメータ	型	必須	説明
filePath	string	○	PSD ファイルの絶対パス
layerId	number	△	レイヤー ID
layerName	string	△	レイヤー名（完全一致）
layerPath	string	△	レイヤーパス（例: Header/Logo）
includeImage	boolean	-	レイヤー画像を含めるか（デフォルト: false）

layerId / layerName / layerPath のいずれか1つを指定してください。

返却内容: bounds、opacity、blendMode、テキスト情報、ベクター情報、エフェクト、スマートオブジェクト情報

---

get_design_tokens - デザイントークン抽出

PSD 全体からカラー・フォント・シャドウ・グラデーションを収集し、構造化データとして出力します。

パラメータ	型	必須	説明
filePath	string	○	PSD ファイルの絶対パス
format	string	-	出力形式: json（デフォルト）/ css-variables / tailwind

出力例（css-variables）:

:root {
  --color-1: #1a202c; /* text:Header/Title */
  --color-2: #3182ce; /* vector:Content/Button */
  --font-1: "Helvetica";
  --shadow-1: -2px 3px 8px 0px #000000;
}

出力例（tailwind）:

{
  "theme": {
    "extend": {
      "colors": { "custom-1": "#1a202c", "custom-2": "#3182ce" },
      "fontFamily": { "custom-1": ["Helvetica"] },
      "boxShadow": { "custom-1": "-2px 3px 8px 0px #000000" }
    }
  }
}

---

get_screenshot - スクリーンショット取得

ドキュメント全体または特定レイヤーの画像を PNG で取得します。

パラメータ	型	必須	説明
filePath	string	○	PSD ファイルの絶対パス
layerId	number	-	特定レイヤーの ID
layerPath	string	-	特定レイヤーのパス
maxWidth	number	-	最大幅 px（デフォルト: 1200）
maxHeight	number	-	最大高さ px（デフォルト: 1200）

---

get_text_content - テキスト一括抽出

全テキストレイヤーの内容とスタイリング情報を抽出します。

パラメータ	型	必須	説明
filePath	string	○	PSD ファイルの絶対パス
layerPath	string	-	特定グループ内に限定するパス

返却内容: 各テキストレイヤーのテキスト内容、フォント名、フォントサイズ、色、行間、文字間隔、テキスト配置、スタイルラン

---

export_image - 画像書き出し

PSD の合成画像または特定レイヤー/グループを PNG/JPEG ファイルとして書き出します。

パラメータ	型	必須	説明
filePath	string	○	PSD ファイルの絶対パス
outputPath	string	○	出力先ファイルパス（例: /tmp/output.png）
layerId	number	-	特定レイヤーの ID
layerPath	string	-	特定レイヤーのパス（例: Header/Logo）
format	string	-	png（デフォルト）/ jpeg
quality	number	-	JPEG 品質（1-100、デフォルト: 92）
scale	number	-	スケール倍率（例: 0.5 = 50%, 2 = 200%）
width	number	-	出力幅 px（アスペクト比維持）
height	number	-	出力高さ px（アスペクト比維持）

---

search_layers - レイヤー検索

レイヤーを名前やタイプで検索します。

パラメータ	型	必須	説明
filePath	string	○	PSD ファイルの絶対パス
query	string	-	レイヤー名の検索クエリ（部分一致）
type	string	-	text / group / bitmap / vector / adjustment / smartObject / all
visible	boolean	-	可視レイヤーのみ / 非表示のみ
hasEffects	boolean	-	エフェクト付きレイヤーのみ

---

get_layout_info - レイアウト解析

グループレイヤー内の子要素間のスペーシング、整列パターン、推奨レイアウト方向を解析します。CSS 実装時の margin/padding/gap/flexbox 方向の判断に活用できます。

パラメータ	型	必須	説明
filePath	string	○	PSD ファイルの絶対パス
layerId	number	△	グループレイヤーの ID
layerPath	string	△	グループレイヤーのパス（例: Header）
layerName	string	△	グループレイヤー名（完全一致）

layerId / layerPath / layerName のいずれか1つを指定してください。

返却内容: レイアウト方向（horizontal/vertical）、子要素間の gap、整列パターン、推奨 CSS（flexbox/grid）

---

get_layer_css - CSS 生成

レイヤーのスタイル情報を CSS 形式で生成します。

パラメータ	型	必須	説明
filePath	string	○	PSD ファイルの絶対パス
layerId	number	△	レイヤー ID
layerName	string	△	レイヤー名（完全一致）
layerPath	string	△	レイヤーパス（例: Header/Logo）
useParentRelative	boolean	-	親グループ基準の相対座標を使うか（デフォルト: true）

layerId / layerName / layerPath のいずれか1つを指定してください。

返却内容: position, size, background, border, border-radius, box-shadow, text styles 等の CSS プロパティ

---

get_design_spec - デザイン仕様書生成

レイヤーまたはグループの実装用デザイン仕様書を一括生成します。CSS、レイアウト情報、テキスト、border-radius、子要素の仕様を再帰的に含む包括的な仕様書です。

パラメータ	型	必須	説明
filePath	string	○	PSD ファイルの絶対パス
layerId	number	△	レイヤー ID
layerName	string	△	レイヤー名（完全一致）
layerPath	string	△	レイヤーパス（例: Header）
maxDepth	number	-	子要素の再帰深度（デフォルト: 3）
includeScreenshot	boolean	-	スクリーンショットを含めるか（デフォルト: true）

layerId / layerName / layerPath のいずれか1つを指定してください。

返却内容: レイヤーごとの CSS、レイアウト解析、テキスト情報、エフェクト、子要素の仕様（再帰）、スクリーンショット

---

compare_design - デザイン差分比較

PSD デザインと実装のスクリーンショットをピクセル単位で比較し、差分を検出します。

パラメータ	型	必須	説明
filePath	string	△	PSD ファイルの絶対パス（PSD と比較する場合）
layerId	number	-	比較対象のレイヤー ID（PSD 使用時）
layerPath	string	-	比較対象のレイヤーパス（PSD 使用時）
designImagePath	string	△	デザイン画像ファイルのパス（画像同士を比較する場合）
implementationImagePath	string	○	実装のスクリーンショット画像ファイルのパス
tolerance	number	-	色差の許容値（0-255、デフォルト: 30）

filePath（PSD）または designImagePath（画像）のいずれかを指定してください。

返却内容: 差分率（%）、差分ヒートマップ画像、差分領域のバウンディングボックス、判定サマリー

---

使い方ガイド

基本的なワークフロー

Step 1: まずドキュメント概要を確認

/path/to/design.psd の構造を教えて

Step 2: 必要な部分のデザイントークンを抽出

/path/to/design.psd のデザイントークンを Tailwind 形式で出力して

Step 3: コード実装を依頼

/path/to/design.psd を React + Tailwind CSS で実装して

よく使うプロンプト例

やりたいこと	プロンプト例
PSD の全体像を把握	design.psd を分析して
ヘッダー部分だけ見たい	design.psd の Header グループの詳細を教えて
使われている色を知りたい	design.psd で使われている全カラーをリストアップして
CSS 変数として出力	design.psd のデザイントークンを CSS 変数で出力して
特定セクションだけ実装	design.psd の Content セクションを HTML/CSS で実装して
テキスト内容を一括取得	design.psd の全テキストを抽出して
ボタンのスタイルを確認	design.psd の Button レイヤーのエフェクトを教えて
スクリーンショットを見たい	design.psd のスクリーンショットを表示して
レイヤーを画像で書き出し	design.psd の Logo レイヤーを /tmp/logo.png に書き出して
レイヤーの CSS を取得	design.psd の CTAButton の CSS を生成して
レイアウト構造を確認	design.psd の Header グループのレイアウトを解析して
デザイン仕様書を作成	design.psd の Content セクションのデザイン仕様書を生成して
実装との差分を比較	design.psd と screenshot.png を比較して差分を教えて

---

PSD ファイルの準備（デザイナー向け）

より良い解析結果のために、PSD ファイル作成時に以下を推奨します。

レイヤー名のルール

• レイヤーには意味のある名前を付ける（レイヤー 1 ではなく Header NavMenu など）
• グループ（フォルダ）でセクションを整理する
• 名前に 英語 を使うとコード生成時にそのままクラス名として活用しやすい

推奨構成例

Header/
  ├── Logo
  ├── NavMenu/
  │   ├── Link-Home
  │   ├── Link-About
  │   └── Link-Contact
  └── HeaderBG
Content/
  ├── HeroTitle
  ├── HeroDescription
  └── CTAButton
Footer/
  ├── Copyright
  └── FooterBG

その他のポイント

• テキストはテキストレイヤーで作成する（ラスタライズしない）
• ベクターシェイプはシェイプレイヤーのまま保持する
• カラーモードは RGB を使用する
• 不要なレイヤーは非表示にするか削除する

---

トラブルシューティング

canvas パッケージのインストールに失敗する

canvas（node-canvas）はネイティブ依存があります。OS ごとの対処法:

macOS:

brew install pkg-config cairo pango libpng jpeg giflib librsvg

Ubuntu / Debian:

sudo apt-get install -y build-essential libcairo2-dev libpango1.0-dev libjpeg-dev libgif-dev librsvg2-dev

Windows: node-canvas の Windows Installation Guide を参照してください。

MCP サーバーが認識されない

1. 設定ファイルのパスが絶対パスであることを確認
2. npm run build が成功していることを確認
3. Claude Code / Cursor / Claude Desktop を再起動
4. 手動でサーバーが起動するか確認:

   echo '{}' | node /path/to/psd-mcp/dist/index.js
   # エラーが出なければ OK（Ctrl+C で終了）
   

PSD ファイルの解析に失敗する

• カラーモード: RGB 以外（CMYK、Lab 等）は一部機能が制限される場合があります
• ファイルサイズ: 非常に大きな PSD（100MB 超）はメモリ不足になる可能性があります
• バージョン: Photoshop CS6 以降で作成された PSD ファイルを推奨します

スクリーンショットが表示されない

• includeScreenshot: true（デフォルト）で呼び出しているか確認
• PSD にフラット化された合成画像が含まれている必要があります
  • Photoshop で保存時に「互換性を優先」にチェックを入れてください

---

技術スタック

ライブラリ	用途
ag-psd	PSD ファイルの解析（レイヤー、テキスト、エフェクト）
canvas	レイヤー画像の描画・リサイズ
@modelcontextprotocol/sdk	MCP プロトコル実装
zod	ツール入力のスキーマバリデーション

---

ライセンス

MIT