Image Puma

Image Puma

デスクトップアプリ、または MCP サーバー経由で AI 内から直接、Web 用の画像をローカルで一括準備できます。画像処理はローカルで実行されます。Image Puma が画像をアップロードしたり、アカウントを必要としたり、その他の余計なことをしたりすることはありません。すべてローカルで画像を処理します。

アプリを使う

GitHub Releases から最新の Image Puma デスクトップインストーラーをダウンロードしてください。

• macOS（Apple Silicon）：Image-Puma.dmg
• Windows：デスクトップインストーラーは近日公開予定です。以下の MCP サーバーを使えば Claude で Windows を完全にサポートしています。または、Windows マシンで npm install && npm run make を実行してソースからビルドできます（Python 3.11 と、背景削除ツールで使用する制限付きの RMBG-2.0 model へのアクセスが必要です）。

デスクトップアプリと MCP サーバーは独立したコンポーネントです。必要に応じて、どちらか一方だけ、または両方をインストールしてください。

インストーラーにはコード署名がありません。これは無料のアプリであり、OS に「本物のアプリ」と認識させるだけのために、Apple の年間 99 ドルの開発者登録料を払うのは避けたいと考えています。そのため、次のようになります。

• macOS では初回起動時にアプリがブロックされます。開くには、アプリを右クリックして「開く」を選択するか、「システム設定」→「プライバシーとセキュリティ」→「一般」に移動し、「このまま開く」をクリックしてください。

• Windows では SmartScreen の警告が表示されます。「詳細情報」をクリックしてから、「実行」をクリックして続行してください。

Claude で使う

Claude Desktop（ワンクリック）

Claude Desktop のワンクリックインストールでは、GitHub Releases の .mcpb バンドルを使用します。

• お使いのコンピューター用のファイルをダウンロードします。
• Claude Desktop で開きます。
• プロンプトが表示されたら、Image Puma にアクセスを許可する画像フォルダーを選択します。
• 再起動を求められた場合は、Claude Desktop を再起動します。

以下のリンクを使用してください。

• Apple Silicon Mac：image-puma-mcp-darwin-arm64.mcpb
• Windows：image-puma-mcp-win32-x64.mcpb

MCPB インストーラーでは、アクセスを許可する画像フォルダーを選択します。Image Puma は、それらのフォルダー内でのみ読み書きできます。

Claude Code に追加する

コーディングセッション（プロジェクトのアセットの最適化、ファビコンの生成、デプロイ用画像の準備など）では、次のコマンドで MCP サーバーを追加します。

claude mcp add --scope user image-puma -- "$(command -v npx)" -y image-puma mcp serve --transport stdio --allow-dir ~/Pictures ~/Downloads ~/Documents

--scope user を付けると、Image Puma をマシン上のすべてのリポジトリとターミナルで使えるようになります。付けない場合は、コマンドを実行したフォルダーでのみ読み込まれます。Image Puma にアクセスを許可するフォルダーに置き換えてください。たとえば、プロジェクトフォルダーを追加すると、そのリポジトリ内の画像を最適化できます（例：「assets/ 内のすべての画像を Web 用に圧縮する」）。

"$(command -v npx)" の部分はそのままコピーしてください。実行時に npx のフルパスに展開されます。npx だけを登録すると一見問題ないように見えますが、接続に失敗します。MCP サーバーは、nvm、fnm、Volta などの Node バージョンマネージャーを含まない最小限の PATH で起動されるためです。詳しくは、以下のNode が見つからない場合をご覧ください。

その後、新しい Claude Code セッションを開始します（VS Code 拡張機能で新しい会話を始めるか、ターミナルで claude を新たに起動します）。MCP サーバーとそのコマンドはセッション開始時に検出されるため、すでに開いているセッションからは認識されません。claude mcp list を実行すれば、いつでも接続状態を確認できます。

代わりにこのリポジトリをクローンした場合は、コマンドでローカルビルドを指定してください（絶対パスを使用します）。

npm install && npm run build:mcp
claude mcp add --scope user image-puma -- "$(command -v node)" /absolute/path/to/Image-Puma/dist/cli.js mcp serve --transport stdio --allow-dir ~/Pictures

その他の MCP クライアント

npx を使って開発者向けにインストールする場合は、許可するフォルダーに絶対パスを指定します。

{
  "mcpServers": {
    "image-puma": {
      "command": "/usr/local/bin/npx",
      "args": [
        "-y",
        "image-puma",
        "mcp",
        "serve",
        "--transport",
        "stdio",
        "--allow-dir",
        "/Users/you/Pictures"
      ]
    }
  }
}

mcpServers JSON のすべての箇所で、許可するフォルダーと command の両方に絶対パスを使用してください。ターミナルで command -v npx を実行し、表示された内容を /usr/local/bin/npx の代わりに貼り付けてください。ネイティブの Windows では、代わりに "command": "cmd" を使い、最初の 2 つの引数として "/c" と "npx" を指定してください。

使用例

インストール後（上記のいずれかの方法）、Claude に自然な言葉で話しかけるだけです。

You： ~/Pictures/site の画像をウェブにアップロードできるよう圧縮して

Claude： 次の内容で実行します。14 枚の画像を受け付けました。WebP に変換し、ウェブ用にサイズを変更して、メタデータを削除します。上書きが発生しないことを確認できるよう、出力先の正確なパスを一覧表示します。実行しますか？

You： はい

Claude： 完了しました。14 枚中 14 枚の処理に成功しました。入力は 41.8 MB、出力は 3.6 MB です。

Image Puma は必ず最初に計画を提示します。どのファイルが受け付けられたか、どの設定が適用されるか、すべての出力がどこに書き込まれるかを確認できます。確認するまでディスクには何も書き込まれません。また、インストール時に許可したフォルダーのみを参照できます。

プロンプトの例：

• これらの画像をウェブにアップロードできるよう圧縮してください：/Users/you/Pictures/site
• これらの画像をメール用に圧縮してください：/Users/you/Desktop/photos
• これらの画像からメタデータを削除してください：/Users/you/Downloads
• これらの画像からサムネイルを作成してください：/Users/you/Pictures/products
• /Users/you/Projects/my-app/logo.png からファビコンとアプリアイコンのセットを生成し、/Users/you/Projects/my-app/public に保存してください

/image-puma コマンド

Image Puma には、説明した画像処理を Image Puma のツールで実行するよう Claude に指示するスラッシュコマンドが 1 つ用意されています。まず計画を提示し、確認を得てから実行します。

/image-puma compress everything in ~/Pictures/site for the web

Claude Code ターミナルで /image-puma と入力すると、コマンドメニューに表示されます（正式名称は /mcp__image-puma__image-puma です）。Claude Desktopでは、同じプロンプトがチャット入力欄の**＋メニュー**にあり、Image Puma の項目に表示されます。

VS Code 拡張機能でも使える単独の /image-puma コマンド（拡張機能のコマンドメニューには MCP プロンプトが表示されません）を利用するには、次の内容を ~/.claude/commands/image-puma.md として保存してください。

---
description: Batch image work via Image Puma (compress, resize, strip metadata, thumbnails, favicons)
---

Use the Image Puma MCP tools for this local image task: $ARGUMENTS

If no task was given, ask which images to process and what result is wanted.

Create a plan first with image_puma_plan — plan only, do not run it yet. Pick a preset with image_puma_list_presets, or use custom settings (schema via image_puma_settings_schema). Show the returned plan, warnings, and planned output paths, and call image_puma_run only after the user explicitly confirms.

以降、新しいセッションではターミナルと VS Code のどちらでも /image-puma を使えるようになります。上記の「Claude Code に追加する」の手順で MCP サーバーが登録されている必要があります。

ファビコンをすばやく生成するには、image_puma_generate_favicon を利用できます。

トラブルシューティング

Node が見つからない

claude mcp list で Image Puma が失敗として表示され、ENOENT: Executable not found in $PATH: "npx"（または "node"）と表示される場合：

image-puma: npx -y image-puma mcp serve ... - ✘ Failed to connect

MCP クライアントは、~/.zshrc や ~/.bashrc を読み込まない最小限の PATH でサーバーを起動します。そのため、nvm、fnm、Volta、asdf 経由でインストールした Node は、ターミナルでは問題なく見つかる場合でも認識されません。絶対パスを指定して登録し直してください。

claude mcp remove image-puma -s user
claude mcp add --scope user image-puma -- "$(command -v npx)" -y image-puma mcp serve --transport stdio --allow-dir ~/Pictures

その後、新しいセッションを開始し、もう一度 claude mcp list を確認してください。

nvm を使う場合は注意が必要です。command -v npx は ~/.nvm/versions/node/v24.13.1/bin/npx のようにバージョンが固定されたパスを返すため、次回 Node をアップグレードするとそのパスは存在しなくなります。アップグレード後に上記の 2 つのコマンドを再実行するか、nvm で管理されていない Node（/opt/homebrew/bin/node または /usr/local/bin/node）を Image Puma に指定して、パスが有効なままになるようにしてください。Image Puma には Node 20.3.0 以降が必要です。

Claude Desktop のユーザーは、これらの手順を省略できます。上記の .mcpb バンドルには、独自の Node ランタイムが同梱されています。

Windows で npx image-puma がローカルのチェックアウトを参照する

Windows では、リポジトリのクローンなど、名前が大文字と小文字を区別せず image-puma と一致するディレクトリ内で npx image-puma ... を実行すると、npm が公開パッケージではなく、そのローカルディレクトリをパッケージ名として解決することがあります。チェックアウトがビルドされていない場合、コマンドは 'image-puma' is not recognized as an internal or external command というエラーで失敗します。

npx image-puma ... コマンドは、別の作業ディレクトリから実行してください。クローンから開発する場合は、npm run build:mcp でビルドし、npx 経由で実行する代わりに、MCP サーバーがローカルの dist/cli.js を直接参照するようにしてください。

その他の問題

組み込みのチェックを実行すると、Node のバージョン、Sharp、ExifTool、および許可したフォルダーに実際に書き込み可能かどうかが報告されます。

npx -y image-puma mcp doctor --allow-dir ~/Pictures

貢献

Image Puma は、Pantheon Network によって現状のまま公開されています。 現在、バグ修正やプルリクエストのレビューは積極的に行っていません。メンテナンスを引き継ぎたい場合は、 お問い合わせください。 開発環境のセットアップ、チェック、ビルドプロセスについては、CONTRIBUTING.mdをご覧ください。

サポートマトリックス

フォーマットと OS の動作については、docs/support-matrix.mdに記載されています。HEIC/HEIF では、まず Sharp を使用します。macOS では、sips を介して ImageIO にフォールバックできます。Sharp で HEVC をデコードできない場合、Windows と Linux では同梱の libheif デコーダーにフォールバックします。