PhotoFresco

AI エージェント向け PhotoFresco

エージェントが、あなたの承認した PhotoFresco ウィンドウで画像を編集できます。レイヤー、マスク、プレビュー、書き出しに対応しています。

PhotoFresco は、ブラウザーで動作する無料の Photoshop クラスの画像エディターです。レイヤー、マスク、調整レイヤー、選択範囲、ブラシ、PSD のインポートと 書き出し、完全な取り消し履歴に対応しています。このリポジトリは、AI エージェントを PhotoFresco に接続します。エージェント（Claude、Cursor、 VS Code、Codex、その他の MCP クライアント、またはコマンドライン経由のスクリプト）が、あなたのコンピューター上の PhotoFresco ウィンドウを操作します。すべての変更を確認でき、接続を許可し、エージェントに何をさせるかを選択でき、いつでも一時停止または停止できます。編集はエディター内で行われるため、すべての変更が履歴に記録され、あなた自身の編集と同じように取り消せます。

上記の録画は、実際のセッションです。MCP クライアントがこのサーバーを呼び出し、エディターをヘッドレスで操作しています。カテゴリ：デザイン／画像編集。

このリポジトリの内容：

• MCP サーバー（photofresco mcp）：エディターの各操作に対応するツール、画像としてのプレビュー、ファイルまたはリソースとしての書き出しに対応しています。ガイド：MCP.md。
• エージェントスキル（skills/photofresco）：PhotoFresco を適切に使うタイミングと方法をエージェントに教えます。
• コマンドライン（photofresco <command>）：開く、保存済みのワークフローを実行する、書き出す、停止する操作ができます。ガイド： CLI.md。
• ローカルコネクター（上記の3つが共有するライブラリ）：CONNECTOR.md。

エディター自体はこのリポジトリには含まれていません。コネクターは photofresco.com でエディターを開きます。

必要条件

• Node.js 22 以降。
• Chromium ベースのブラウザーがインストールされていること：Google Chrome、Microsoft Edge、または Chromium 120 以降。 ダウンロードは行われません。必要に応じて、--browser（または PHOTOFRESCO_BROWSER）で別のブラウザーを指定してください。
• macOS で動作確認済みです。Windows と Linux は実装済みですが、まだ動作確認されていません。

エージェントを設定する

ワンクリック（Cursor、VS Code、LM Studio）：

各ボタンを押すと、アプリに photofresco サーバーが追加されます。GitHub のバージョン 0.1.0 のソースアーカイブ（コミット 328cfaf）から npx で起動します（npm レジストリから取得されるものはありません）。フォルダーへのアクセス権は付与されません。エージェントがファイルを開いたり保存したりできるようにするには、アプリの MCP 設定で mcp の後に --read 引数と --write 引数を追加してください。

または、以下のクライアントの MCP 設定にサーバーを追加してください。エージェントがファイルを開けるフォルダー（--read）と、書き出したファイルを保存できるフォルダー（--write）を選択してください。これらの指定がない場合でも、エージェントは編集やプレビューを行えますが、ファイルにはアクセスできません。

npm リリースは準備中です。 photofresco npm パッケージは 2026 年 10 月中旬に公開されるため、以下の npx -y [email protected] コマンドはまだ動作しません。それまでは、[email protected] の代わりに --package=https://github.com/photofresco/photofresco-agent/archive/328cfaf3caf6483c5660381f19f2afdb2059a215.tar.gz photofresco （GitHub から取得する同じバージョン）を指定するか、プラグインとしてインストールするか、以下のようにこのリポジトリのクローンから実行してください。npx -y [email protected] の部分を node /path/to/photofresco-agent/src/bin/photofresco.js に置き換えてください（npm install は不要です）。

クローンから実行する場合（今すぐ動作します。MCP SDK はバンドルされているため、インストールするものはありません）：

git clone https://github.com/photofresco/photofresco-agent.git ~/photofresco-agent

次に、mcpServers を読み込む任意のクライアント（Claude Desktop、Cursor、Windsurf、Kiro など多くのクライアント）に、このエントリーを追加してください。/Users/you の部分は、ご自身のホームフォルダーに置き換えてください。

{
  "mcpServers": {
    "photofresco": {
      "command": "node",
      "args": ["/Users/you/photofresco-agent/src/bin/photofresco.js", "mcp", "--read", "/Users/you/Pictures", "--write", "/Users/you/Pictures/PhotoFresco"]
    }
  }
}

Claude Code：

claude mcp add photofresco -- npx -y [email protected] mcp --read ~/Pictures --write ~/Pictures/PhotoFresco

Claude Desktop：claude_desktop_config.json（Settings → Developer → Edit Config）：

{
  "mcpServers": {
    "photofresco": {
      "command": "npx",
      "args": ["-y", "[email protected]", "mcp", "--read", "/Users/you/Pictures", "--write", "/Users/you/Pictures/PhotoFresco"]
    }
  }
}

Cursor：~/.cursor/mcp.json（すべてのプロジェクト）または .cursor/mcp.json（1 つのプロジェクト）。Claude Desktop と同じ mcpServers エントリーを使用します。

VS Code：ワークスペース内の .vscode/mcp.json、またはすべてのワークスペースで使用する場合は MCP: Open User Configuration：

{
  "servers": {
    "photofresco": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "[email protected]", "mcp", "--read", "/Users/you/Pictures", "--write", "/Users/you/Pictures/PhotoFresco"]
    }
  }
}

Windsurf（Cascade）：Claude Desktop と同じ mcpServers エントリーを mcp_config.json に追加します（Cascade → MCPs → Open MCP config file）。

Gemini CLI：

gemini mcp add -s user photofresco npx -y [email protected] mcp --read ~/Pictures --write ~/Pictures/PhotoFresco

Codex：

codex mcp add photofresco -- npx -y [email protected] mcp --read ~/Pictures --write ~/Pictures/PhotoFresco

OpenCode：プロジェクト内の opencode.json、またはすべてのプロジェクトで使用する場合は ~/.config/opencode/opencode.json（上記と同様にクローンから実行します）：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "photofresco": {
      "type": "local",
      "command": ["node", "/Users/you/photofresco-agent/src/bin/photofresco.js", "mcp", "--read", "/Users/you/Pictures", "--write", "/Users/you/Pictures/PhotoFresco"],
      "enabled": true
    }
  }
}

Kiro：上記のクローン用 mcpServers エントリーを、~/.kiro/settings/mcp.json（すべてのワークスペース）または .kiro/settings/mcp.json（1 つのワークスペース）に追加します。

Cline：このリポジトリを Cline に渡してください。llms-install.md では、インストール、接続、停止の手順を案内しています。

このサーバーは、公式 MCP TypeScript クライアントを使い、stdio 経由でテストされています。以下の各エントリーは、各アプリのドキュメントに記載された stdio 形式に準拠しています。オプション：

オプション	意味
--read <folder>	エージェントがこのフォルダーから画像ファイルを開けるようにします（複数指定可）
--write <folder>	エージェントがこのフォルダーと新しいサブフォルダーに書き出したファイルを保存できるようにします（複数指定可）
--overwrite	--write フォルダー内の既存ファイルを置き換えて書き出せるようにします（エージェントはこの指定についても確認する必要があります）
--tools <groups>	ツールとして一覧表示する操作を指定します。essentials（デフォルト、最大 40 ツール）、all、またはグループをカンマ区切りで指定します（MCP.md）
--profile <folder>	ブラウザープロファイルのフォルダーを指定します。使い捨てのプロファイルには ephemeral を指定します
--browser <path>	使用する Chromium ベースのブラウザーを指定します（PHOTOFRESCO_BROWSER と同じです）

MCP バンドル（Claude Desktop など、.mcpb ファイルをインストールするアプリ向け）：node scripts/build-mcpb.mjs を実行すると、このリポジトリから dist/photofresco-mcp-0.1.0.mcpb とその SHA-256 が生成されます（同じ Node.js バージョンを使えば再現可能です）。このバンドルは同じサーバーを起動し、プラグインと同様にフォルダーへのアクセス権を付与しません。各 GitHub リリースにはこのファイルが添付されます。その SHA-256 は、server.json の fileSha256（Official MCP Registry のエントリー）に記載されています。

Docker（コンテナー内でサーバーをチェックする MCP レジストリ向け）：docker build -t photofresco-mcp . を実行し、次に docker run -i --rm photofresco-mcp を実行すると、stdio 経由でサーバーが起動します。このイメージにはブラウザーが含まれていないため、ツールの一覧表示のみが可能です。ここでは photofresco_connect は browser_not_found で失敗します。画像の編集には、上記のようにローカルにインストールして実行してください。

セッションの流れ

1. エージェントが photofresco_connect を呼び出します。PhotoFresco が専用のウィンドウで開き、接続コードが表示されます。エージェントも同じコードを伝えるので、確認して Allow をクリックします。
2. セッションは権限なしで開始します。エージェントが必要な権限（Read、Edit、Export。Send と Spend はクラウドおよび有料 AI の場合のみ）を要求し、Permissions ダイアログで選択します。許可すると、編集ツールがエージェントに表示されます。
3. エージェントはエディター操作ごとにツールを1つ使って編集し、プレビューを確認して、気に入らない操作を元に戻します。自分で編集すると、Resume を押すまでエージェントは一時停止します。Stop を押すか、ウィンドウを閉じるとセッションが終了します。

エージェントが photofresco_connect を呼び出すまでは、何も開きません。サーバーを起動してツールを一覧表示しても、ブラウザーは起動しません。

プラグインとしてインストールする

このリポジトリは、Claude Code、Codex、Cursor、Gemini CLI、Hermes Agent、OpenClaw、 Antigravity、Devin、Kiro 用のプラグインでもあります。1回のインストールで MCP サーバーと エージェントスキルが追加されます。クライアントはリポジトリをコピーし、 node <plugin folder>/src/bin/photofresco.js mcp でサーバーを起動します。MCP SDK は ベンダーに読み取り可能な状態で同梱されているため、npm からダウンロードされるものはありません。 Node.js 22 以降が PATH に必要です。

プラグインをインストールしても、フォルダーへのアクセス権は付与されません。エージェントは PhotoFresco のウィンドウで開いている画像を編集し、ファイルの開閉と保存はユーザー自身が行います。エージェントにファイルへのアクセス権を与えるには、前述のとおり --read と --write を指定してサーバーを設定してください。

Claude Code（セッション内。3行目は Claude Code 2.1.275 以降で2つの手順をまとめて実行します）：

/plugin marketplace add photofresco/photofresco-agent
/plugin install photofresco@photofresco
/plugin install photofresco --marketplace photofresco/photofresco-agent

Codex：

codex plugin marketplace add photofresco/photofresco-agent
codex plugin add photofresco@photofresco

Gemini CLI：

gemini extensions install https://github.com/photofresco/photofresco-agent

Gemini CLI は拡張機能に渡す環境変数が少ないため、この拡張機能には PHOTOFRESCO_BROWSER が 渡されません。標準の場所にないブラウザーを使う場合は、前述の MCP 設定を使用してください。

Cursor：一覧に表示されたら Customize から PhotoFresco をインストールするか、このリポジトリを ~/.cursor/plugins/local/photofresco にコピーして、ウィンドウを再読み込みしてください。

Hermes Agent（Agent Plugins に対応するバージョンで、hermes plugins validate があるもの）。プラグインは インストール時には無効になっています。有効にすると、次のセッションでサーバーとスキルが読み込まれます：

hermes plugins install photofresco/photofresco-agent --no-enable
hermes plugins enable photofresco

OpenClaw（ソースの確認後、プラグインの MCP サーバーとスキルの承認を求められます）：

openclaw plugins install photofresco --marketplace photofresco/photofresco-agent

Antigravity（CLI）：

agy plugin install https://github.com/photofresco/photofresco-agent

Devin（CLI。またはアプリで Customize → Plugins → Add plugin → From repository）：

devin plugins install photofresco/photofresco-agent

Kiro：Powers → Add Custom Power → Import power from GitHub を選択し、 https://github.com/photofresco/photofresco-agent を指定します。

マニフェストは .claude-plugin/（Claude Code。Devin も読み込みます）、mcp.json を含む plugin.json （Agent Plugins 標準。Codex、Hermes Agent、Kiro で使用）、 .cursor-plugin/plugin.json（Cursor と、これを介して .mcp.json を読み込む OpenClaw）、 gemini-extension.json（Gemini CLI）、mcp_config.json（Antigravity）、openclaw.plugin.json （OpenClaw と ClawHub のメタデータ）です。

エージェントスキル

skills/photofresco にある Agent Skill は、 スキル対応エージェント（Claude Code、Codex、Cursor など）に、PhotoFresco を使うタイミング、接続方法と権限の要求方法、 位置確認 → 編集 → プレビュー → 元に戻すという作業サイクル、ワークフロー、エクスポート、 すべてのエラーコード、コマンドラインについて説明します。MCP サーバーの設定は行わないため、前述のとおり設定してください。 skills CLI を使って、現在のプロジェクトにインストールします （ユーザー用にインストールする場合は -g を指定します）：

npx skills add photofresco/photofresco-agent

npx skills remove photofresco で削除できます。操作のリファレンスはサーバー独自のツール一覧 （photofresco_list_tool_groups、またはコマンドラインで photofresco ops）です。

コマンドライン

同じパッケージに、シェルは使えるものの MCP クライアントがないスクリプトやエージェント向けの photofresco コマンドもインストールされます。このコマンドは、バックグラウンドのコネクタープロセスを通じて、同じ種類の承認済みウィンドウを操作します。npm パッケージが公開される（2026年10月中旬）までは、npm install -g ではなく、クローンから実行してください：alias photofresco="node /path/to/photofresco-agent/src/bin/photofresco.js"。

npm install -g [email protected]
photofresco connect --read ~/Pictures --write ~/Pictures/PhotoFresco
photofresco run warm.json --open ~/Pictures/beach.png --input amount=0.6 \
  --export ~/Pictures/PhotoFresco/beach-warm.png
photofresco stop

connect は PhotoFresco を開いて接続コードを表示します。ウィンドウに同じコードが表示されていることを確認し、許可をクリックして権限を選択してください。run は新しいタブで画像を開き、保存済みのワークフロー（エディターのアクションパネルからエクスポートされる移植可能なファイル）を実行し、SHA-256 が一致した場合にのみエクスポートを書き込みます。stop はセッションを終了し、ウィンドウを閉じてコネクタープロセスを停止します。

コマンド	機能
connect	必要に応じてコネクターを起動し、PhotoFresco を開いてペアリングします（許可をクリックします）
status	コネクター、ウィンドウ、セッション、権限、許可されたフォルダーを表示します
request-access <list>	追加の権限を要求します（read,edit,export,external-write,spend）
documents, attach <id>	開いているドキュメントを一覧表示します。別のドキュメントを対象にします
open <file>	許可されたフォルダー内の画像を新しいタブで開きます
run <workflow.json>	--open、--input、--export を指定してワークフロー（または --action <id>）を実行します
export <file>	ドキュメントを許可されたフォルダーにエクスポートします（PNG、PSD、または .pfd）
exec <op> [params-json]	エディターの操作を1つ実行します
ops [prefix], describe <op>	このセッションで実行できる操作と、そのパラメーターを表示します
outcome <request-id>	接続が切れた後に、以前のリクエストの結果を取得します
disconnect, stop	セッションを終了します。stop はウィンドウとコネクターも閉じます
mcp	上記の MCP サーバー

すべてのコマンドで --json を指定できます（成功時も失敗時も、標準出力に1つのオブジェクトを出力します）。また、仕様化された終了コードを返します（0：成功、2：使用方法の誤り、3：未接続、4：パスが拒否された、5：エディターに拒否された、8：キャンセル、75：ユーザーの操作待ち）。詳細なリファレンス：CLI.md。

実行、送信、取得されるもの

macOS 上で Chrome for Testing 145 をローカルのエディターのビルドに接続して観察した内容は、詳細とともに DISCLOSURE.md に記録されています。観察されていない内容には、その旨が記載されています。

実行されるもの

• Node.js プロセス：クライアントが起動する MCP サーバー（クライアントを閉じると終了）、または photofresco コマンドごとに1つと、データフォルダーごとに1つのバックグラウンドコネクタープロセス（photofresco stop の実行時、ウィンドウを閉じたとき、またはウィンドウもコマンドもない状態が1分続いたときに終了します）。
• 1つのブラウザープロセスツリー。エージェントが接続した場合にのみ起動します。専用のプロファイルと DevTools パイプ（--user-data-dir=<profile> --remote-debugging-pipe --no-first-run --no-default-browser-check --disable-extensions）を使用して起動する、インストール済みの Chrome、Edge、または Chromium です。通常の表示ウィンドウが開きます（上記のデモはヘッドレスで記録されました）。普段使用しているブラウザーのプロファイルが開かれたり、読み取られたり、接続されたりすることはありません。
• その他のプログラム、シェルコマンド、インストーラー、サービス、ログイン項目、拡張機能は実行されません。

ローカルファイルと通信経路

• データフォルダー：~/Library/Application Support/PhotoFresco Connector（macOS）、%LOCALAPPDATA%\PhotoFresco Connector（Windows）、または ~/.local/share/photofresco-connector （Linux）。ブラウザープロファイル（ここでサインインした場合の Cookie とサインイン情報、キャッシュ、エディターのローカルストレージと自動保存データ）、ロックファイル、およびコマンドライン用の cli/（Unix ソケット（0700 のフォルダー内に 0600 で配置）、起動ごとに生成されるランダムキー、connector.log）が保存されます。connector.log に記録されるのは、許可されたフォルダーパス、読み書きしたファイルのパス、サイズ、SHA-256 などの機密情報を含まないイベントのみです。キー、ファイルの内容、ピクセルは記録されず、最大 4 MiB です。
• ファイル：エージェントがファイルを開くと、--read フォルダー内のみから読み取られます（最大 32 MiB）。エクスポート時は --write フォルダー内のみに、一時ファイルとして書き込み、その SHA-256 が一致した後に所定の場所へ名前を変更します。既存のファイルは、--overwrite を指定し、エージェントが上書きを求めた場合にのみ置き換えられます。
• リッスンするネットワークポートはありません。 ブラウザーは専用のプライベートパイプ経由で制御され、コマンドラインはローカルソケットを使用します。確認済み：サーバーまたはコネクタープロセスに TCP ソケットはありません。

ネットワーク

• コネクター、MCP サーバー、コマンドラインは、それ自体ではネットワークリクエストを行いません。npx／npm install は、まず npm レジストリからパッケージをダウンロードします（npm リリースまでは、ワンクリックボタンが代わりに GitHub からこのリポジトリのソースアーカイブをダウンロードします）。プラグインのインストール時には、エージェントクライアントがこのリポジトリを GitHub からコピーします。サーバーの起動時には何もダウンロードされません。
• ブラウザーは https://photofresco.com/app/?pf_ref=mcp（または cli）を開き、アトリビューション用の秘密情報を含まないタグを付けて、通常の訪問と同じようにエディターを読み込みます。ブラウザーは自動操作されるため、サードパーティ広告は表示されません。
• コネクターのウィンドウでは、セッション記録がオフの状態で起動します。 エディターは、コネクターが開いたウィンドウ（リンクやウェブサイトでは設定できない専用のチャネル）を認識し、［データとプライバシー］で何も許可されていない状態で起動します。そのため、ファイルから何もアップロードされません。セッション記録、診断データ、エージェントが開いたファイルのコピー、使用状況イベントは送信されません。確認済み：接続からセッション終了まで、エージェントが写真をインポートした後も、記録やテレメトリのリクエストはありません。エージェントを許可すると、そこで［外部エージェント］のみがオンになります。
• そのウィンドウの［データとプライバシー］で記録をオンにしない限り、記録はオフのままです。オンにすると、PhotoFresco に入力イベント、エディターコマンド、ドキュメント名、入力テキスト（パスワード欄とメールアドレス欄はマスクされます）、ウィンドウで開いた各画像のコピー（コネクター経由でエージェントが開いたファイルを含み、各ファイル最大 16 MiB、ページ読み込みごとに 6 個まで）が送信されます。また、診断データ（エラー、機能イベント、パフォーマンス、デバイスプロファイル）とプライバシーに配慮した使用状況イベント（referral、open、edit、export。automated とマークされ、ファイル名やピクセルは含まれません）も送信されます。コネクターが開いていない photofresco.com への通常の訪問では、記録はデフォルトでオンです。
• ブラウザー自体のバックグラウンド通信（更新、安全なブラウジング）は、デフォルト設定に従います。測定していません。本番サイトからのサードパーティリクエストは検証していません。

エージェントが受け取る情報

• 許可した内容のみです。セッションの状態、ドキュメントの状態、操作結果、プレビュー（ピクセル）、エクスポートしたファイルです。エージェントが受け取る情報はすべて、エージェントのモデルプロバイダーのポリシーに基づいて、そのプロバイダーに送信されます。
• 有料 AI 機能を実行できるのは、［支出］の権限と設定したクレジット予算がある場合のみです。PhotoFresco のサービス（クラウドドキュメント、AI）へのデータ送信には、［送信］の権限が必要です。
• ウィンドウには、接続している相手の名前が表示されます。MCP クライアントがハンドシェイクで送信する名前（「 via MCP」）、またはコマンドラインの --client の値（デフォルトは「Terminal via CLI」）です。

操作の決定権は常にあなたにあります。接続ごとにあなたの許可が必要で、セッションは権限のない状態で開始します。停止、ウィンドウを閉じる、再読み込み、またはエディターを離れるとセッションは終了します。コネクターを閉じると、そのウィンドウも閉じます。

アンインストール

クライアントの設定から MCP エントリーを削除するか（または photofresco stop と npm uninstall -g photofresco を実行する）、プラグインを削除します（Claude Code では /plugin uninstall photofresco@photofresco、 codex plugin remove photofresco@photofresco、gemini extensions uninstall photofresco、 hermes plugins remove photofresco、openclaw plugins uninstall photofresco、 agy plugin uninstall photofresco、devin plugins remove photofresco を実行するか、Cursor の Customize および Kiro の Powers パネルから削除します）。npx skills remove photofresco を実行してスキルを削除し、上記のデータ フォルダーを削除します。それ以外にインストールされるものはありません。

サポート

• ご質問やバグの報告：GitHub issues または [email protected]。
• ドキュメント：AI エージェントで PhotoFresco を使用する。
• プライバシーポリシー：photofresco.com/docs/privacy。
• 利用規約：photofresco.com/docs/terms。
• ウェブサイト：photofresco.com。

ライセンス

このリポジトリ（MCP サーバー、コマンドライン、コネクター、スキル）は、 MIT License の下で公開されています。PhotoFresco エディターと photofresco.com サービスは含まれません。