pixel-surgeon

pixel-surgeon-mcp

AI による画像・動画の生成、編集、および移植手術レベルの領域修復を行う MCP サーバー
Gemini 3.1 Flash Image、OpenAI GPT Image 2、Grok Imagine、Veo 3 を活用

---

Claude（または任意の MCP クライアント）に、自然言語で画像の生成・編集、文字化けの修正、動画の作成を行う機能を提供する MCP サーバーです。

動作の仕組み

pixel-surgeon-mcp は、複数のプロバイダーに対応した画像生成サーバーです。任意のプロバイダーを組み合わせて利用でき、リクエストごとに切り替えられます。

Gemini（Google）— バランス重視

Google の画像生成パイプラインでは、2 段階の方式を採用しています。まず Gemini 3.1 Pro がプロンプトを推論し、次に Gemini 3.1 Flash Image がピクセルを描画します。512／1K／2K／4K の解像度で、9 種類のアスペクト比に対応しています。価格と性能のバランスに優れ、無料枠も利用できます。

OpenAI GPT Image 2 — 最高品質

テキスト描画と視覚的な忠実度が大幅に向上した、OpenAI の最新画像モデルです。柔軟な解像度に対応しており、pixel-surgeon が選択したサイズとアスペクト比を最適なピクセル寸法に自動で割り当てます。品質レベルは medium（高速）と high（印刷対応）です。他のモデルが苦手とするインフォグラフィック、図、テキストの多い画像の生成に最適です。生成速度は遅く、コストも高くなります。

Grok Imagine（xAI）— 最速

xAI の Aurora を搭載した画像モデルです。生成速度が最速で、コストも最も低くなっています。固定解像度（約 1K）で、7 種類のアスペクト比に対応しています。迅速なプロトタイピングや反復作業に適しています。

Veo 3（動画）

動画生成では、サーバーが非同期ポーリングを使って Veo 3 を呼び出し、動画と環境音の両方を生成します。16:9 と 9:16 のアスペクト比に対応し、長さは 5 秒または 8 秒です。

領域修復

AI 画像モデルは、テキストの多い画像を苦手としています。修復ツールは、画像の小さな領域をプロバイダーに送信し、ヒストグラムを合わせた合成で結果を元の画像に継ぎ合わせ、自然になじませることで、この問題を解決します。

ツール

ツール	説明
generate_image	テキストから画像を生成（1 枚）
generate_images	並列バッチ生成（1～8 枚）
generate_video	Veo 3 で音声付きのテキストから動画を生成（5 秒または 8 秒）
edit_image	自然言語の指示で既存の画像を編集
fix_image	文字化けしたテキストを修復するグリッドベースのタイル修復（2x2、3x3 など）
fix_region	アスペクト比を自動調整する、対象を絞った領域修復
interactive_fix	複数ショットを選択できる、ブラウザー上の切り抜き UI
list_images	生成した画像と動画を一覧表示
save_image	外部画像をワークスペースに取り込む
remove_background	画像の背景を削除（アルファチャンネルによる透過）

モデル

モデル	プロバイダー	解像度	最適な用途
gemini-3.1-flash-image	Google	512 / 1K / 2K / 4K	汎用画像生成、写実的なシーン
gemini-2.5-flash-image	Google	最大1K（無料枠）	手早い下書き、プロトタイピング
gpt-image-2	OpenAI	柔軟（最大4K）	テキスト中心の画像、インフォグラフィック、図表、タイポグラフィ
gpt-image-1	OpenAI	固定の3サイズ	レガシー対応
grok-imagine	xAI	固定（比率ごとに約1K）	高速な反復、最小コスト

呼び出しごとに特定のモデルを指定するには、model ツールパラメーターを使用するか、DEFAULT_IMAGE_MODEL 環境変数を設定してください。

Gemini の自動フォールバック

Gemini の生成呼び出しが課金／前払いエラーで失敗した場合、サーバーは自動的に無料枠の gemini-2.5-flash-image モデルで再試行します。この場合、ビューアーに黄色のバナーが表示されます。無料枠の制限：最大解像度1K、10 RPM、500 RPD。

スタイルプリセット

すべての生成ツールと編集ツールで、オプションの style パラメーターを使用できます。

neo-brutalist

雑誌のエディトリアル、力強いタイポグラフィ、網点テクスチャ。クリーム、黒、テラコッタのパレットです。

duval-software-infographic

Duval Software 独自のレトロフューチャーなインフォグラフィックスタイル。1960年代の宇宙時代と1980年代のアーケードを融合しています。カソードブルー、アンバー、サーモンのパレットです。図表やシステム概要に最適です。

fractal-arcade

ディザリングされたフラクタル、シェルピンスキー図形、ローポリ。CRT風のレトロスタイルで、Amiga/EGA のパレットです。

clean-tech-infographic

技術図、システムフロー、データパイプライン。ダークネイビー、シアン、エレクトリックブルーです。

セットアップ

API キーを取得する

少なくとも1つのプロバイダーの API キーが必要です。柔軟性を最大限に高めるため、任意の組み合わせで使用できます。

Google（Gemini + Veo 3）

1. Google AI Studio にアクセスします
2. Google アカウントでサインインします
3. Create API Key をクリックして、キーをコピーします

前払いが必要です。 Gemini 3.1 Flash Image と Veo 3 では、課金設定とクレジットの前払いが必要です。無料枠のフォールバック（2.5 Flash）には、解像度とレートの制限があります。Google AI の料金をご覧ください。

OpenAI（GPT Image 2）

1. OpenAI API にアクセスします
2. サインインするか、アカウントを作成します
3. Create new secret key をクリックして、キーをコピーします
4. API クレジットがあることを確認してください。画像生成はリクエストごとに課金されます

GPT Image 2 は、テキスト描画、インフォグラフィック、図表に優れています。テキスト中心の画像が主な用途であれば、このプロバイダーをお使いください。

xAI（Grok Imagine）

1. xAI Console にアクセスします
2. サインインするか、アカウントを作成します
3. API キーを作成してコピーします

Grok Imagine は最速かつ最安のプロバイダーです。素早い反復やプロトタイピングに最適です。出力解像度は固定（約1K）で、サイズは制御できません。

クイックスタート（npx）

インストールは不要です。npx から直接実行できます。お持ちの API キーを渡してください：

npx pixel-surgeon-mcp

Claude Code CLI

claude mcp add pixel-surgeon \
  -e GOOGLE_API_KEY=your-google-key \
  -e OPENAI_API_KEY=your-openai-key \
  -e XAI_API_KEY=your-xai-key \
  -- npx pixel-surgeon-mcp

Claude Desktop / MCP クライアントの設定

{
  "mcpServers": {
    "pixel-surgeon": {
      "command": "npx",
      "args": ["pixel-surgeon-mcp"],
      "env": {
        "GOOGLE_API_KEY": "your-google-api-key",
        "OPENAI_API_KEY": "your-openai-api-key",
        "XAI_API_KEY": "your-xai-api-key"
      }
    }
  }
}

ソースからインストール

ローカルにクローンして使用する場合：

git clone https://github.com/j-east/pixel-surgeon-mcp.git
cd pixel-surgeon-mcp
npm install
npm run build

画像の出力

生成された画像は ~/Pictures/pixel-surgeon/ に保存されます。初回使用時にローカルのブラウザビューアーが自動起動し、モデル選択、再生成コントロール、検索機能を備えたフル解像度のプレビューを表示します。

開発

npm run dev    # tsx watch mode
npm run build  # compile TypeScript
npm run start  # run compiled server

主な実装の詳細

• アスペクト比のスナップ — 中心点を維持しながら、クロップをGeminiがサポートする最も近い比率に調整します
• ヒストグラムマッチング — チャンネルごとにRGBを正規化し、合成領域がシームレスになじむようにします
• 人間が介在するワークフロー — interactive_fix はブラウザーのクロップUIを開き、ユーザーが送信するまでPromiseで処理をブロックし、Geminiへの呼び出しを並列実行して、ユーザーが最適な結果を選べるようにします
• MCPのサイズ制限 — フル解像度の画像はディスクに保存し、ダウンサンプリングしたバージョン（< 950KB）をMCPレスポンスで返します

コントリビューション

PRを歓迎します！特に、以下を募集しています。

新しいスタイルプリセット

src/index.ts の STYLE_PRESETS オブジェクトにエントリーを追加してください。PRには以下を含めてください。

• プリセット定義（名前、プロンプトのプレフィックス、デフォルトのアスペクト比）
• そのプリセットで生成したサンプル画像2～3枚（PRの説明に添付してください）
• READMEの表に記載する、ビジュアルスタイルの簡単な説明

モデルアダプター

現在、このサーバーはGemini、OpenAI、Grok Imagine、Veo 3をサポートしています。Stable DiffusionやFluxなど、ほかの画像・動画生成API向けのアダプターも歓迎します。追加をご希望の場合は、インターフェースの認識を合わせるため、まずIssueを作成してください。

Duval Software製

pixel-surgeon-mcpは、Duval Softwareのエンジニアリングチームの一員であるJohn Evansがメンテナンスしています。Duval Softwareは、フロリダ州ジャクソンビルビーチを拠点とするソフトウェアエンジニアリング企業で、AIを活用したツールやカスタム統合を開発しています。MCPサーバー、AIパイプライン、本番環境向けツールの開発をご希望の場合は、お問い合わせください。

ライセンス

MIT