UpscaleX

UpscaleX MCP/CLI

UpscaleXは、RealESRGAN、Vulkan GPUハードウェアアクセラレーション、Lanczosスーパーサンプリングを活用した、8Kおよび16K対応のプロダクショングレードな画像アップスケーラーCLI兼Model Context Protocol（MCP）サーバーです。

デジタル印刷のワークフロー、大判ポスターの制作、美術作品の複製、Claude Desktop、Antigravity、Cursorで動作する自律型AIコーディングエージェント向けに設計されています。

すぐにセットアップしたい場合は、AIエージェント向けのコピー＆ペースト可能なセットアッププロンプトと手動での手順を記載したインストールガイドをご覧ください。または、UpscaleX Agent SkillをAIコーディングアシスタントに提供してください。

---

目次

• 主な機能
• インストールガイド
• AIエージェントスキル
• 画質の比較
• ドキュメント一覧
• uvでのクイックスタート
• コマンドラインインターフェース
• Model Context Protocol（MCP）との連携
• モデル一覧
• テストと検証
• コントリビューション
• ライセンス

---

主な機能

• デュアルモード動作：対話型コマンドラインインターフェース（upscalex）と標準のModel Context Protocolサーバー（upscalex-mcp）。
• 8Kおよび16Kプリセット：
  • 16K：ネイティブの4x RealESRGAN深層学習モデルによるアップスケールで、最大400+メガピクセルのマスターファイルを生成します。
  • 8K：4xの深層学習推論後にLanczos-3でダウンサンプリング（スーパーサンプリングアンチエイリアシング／SSAA）し、エッジをシャープに保ち、ノイズをゼロに抑えます。
  • カスタムサイズ：任意の解像度または印刷時の物理的なアスペクト比に合わせて、縦横比を維持した拡大縮小が可能です。
• クロスプラットフォーム設計：Windows、Linux（Ubuntu、Debian、Fedora）、macOS（Apple Silicon arm64およびIntel x86_64）でテストされ、サポートされています。
• シームレスなCPUフォールバックに対応したGPUアクセラレーション：Vulkan対応のディスクリートGPU（NVIDIA RTX/GeForce、AMD Radeon、Intel Arc/Iris、MoltenVK経由のApple Silicon）を自動検出して利用します。ヘッドレスDockerコンテナやGPUドライバーのない環境では、エンジンがマルチスレッドCPU Lanczos超解像に切り替わるため、クラッシュしません。
• ハードウェア診断：統合されたupscalex doctorコマンドで、システムの演算デバイス、Vulkanのサポート、推奨タイルサイズを調べられます。
• メモリセーフなタイル処理：スライディングウィンドウによる空間タイル分割（--tile-size 256）で、4GBから8GBのGPUでもメモリ不足（OOM）による失敗を起こさず、超ギガピクセル画像を処理できます。
• エンジンの自動セットアップ：プラットフォーム用のコンパイル済みバイナリがローカルに見つからない場合、自動的にダウンロードして検証します。
• 印刷品質の分析：300 DPI、150 DPI、72 DPIでの印刷時の物理サイズをインチおよびセンチメートル単位で自動計算します。

---

画質の比較

以下は、低解像度でピクセル化されたソース画像（663 × 531 px、0.35 MP）を、realesrgan-x4plus モデルを使用して高精細な印刷品質（2,652 × 2,124 px、5.63 MP）にアップスケールした、UpscaleX 4x 超解像再構成の実証的な比較です。

指標	元のソース画像	UpscaleX 4x 出力
ピクセル寸法	663 × 531	2,652 × 2,124
総メガピクセル数	0.35 MP	5.63 MP（ピクセル数は16倍）
エッジの再構成	強いブロック状のピクセル化、リンギング	円形のスポークを再構成し、輪郭を鮮明化
300 DPI での最大印刷サイズ	2.2 × 1.8 インチ	8.8 × 7.1 インチ
モデル	—	realesrgan-x4plus
ハードウェア	—	NVIDIA GeForce RTX 3050 Laptop GPU（10.8秒）

---

ドキュメント一覧

包括的な技術ガイドは、docs/ ディレクトリおよびリポジトリのルートにあります。

• インストールガイド：AI エージェントによる自律的なコピー＆ペースト用プロンプトと、手動でのインストール手順です。
• AI エージェントスキル仕様：Claude、Cursor、Antigravity 向けの標準エージェントスキル定義です。
• CLI リファレンスガイド：フラグの詳細、タイリング戦略、実行例を網羅しています。
• Model Context Protocol（MCP）ガイド：JSON-RPC ツールの契約、パラメータースキーマ、複数クライアントの設定について説明します。
• アーキテクチャと数学的仕様：ディープラーニングの基礎、RRDB ネットワーク、Lanczos カーネル、メモリ上限について詳しく説明します。
• エラー処理とトラブルシューティング：既知の障害モード、実行前のサニタイズ、復旧手順について説明します。
• コントリビューションガイド：コード規約、テスト手順、プルリクエストのワークフローについて説明します。

---

クイックスタート

オプション 1：PyPI からインストール（CLI と MCP に最適）

pip install upscalex

オプション 2：ソースをクローンしてインストール（uv を使用）

git clone https://github.com/The-Open-Source-Founder/upscalex.git
cd upscalex

# Create virtual environment and install package
uv venv
uv pip install -e .

利用可能なモデルを確認する

upscalex models

---

コマンドラインインターフェース

16K アップスケール（デフォルトの 4x モデル）

upscalex upscale input.png --target 16k

8K スーパーサンプリング・アップスケール

upscalex upscale poster.png --target 8k -o poster_8k.png

2D イラスト／アニメ作品

upscalex upscale graphic.png --model realesrgan-x4plus-anime --target 8k

画像と印刷サイズの確認

upscalex info input.png

ハードウェアとコンテンツに応じたモデルの推奨

upscalex recommend input.png

すべてのオプションと引数については、CLI ガイドを参照してください。

---

Model Context Protocol（MCP）との統合

UpscaleX は stdio を介してネイティブ MCP サーバーとして動作し、AI エージェント（Claude Desktop、Cursor、Antigravity、Windsurf、Zed）が画像のメタデータを確認し、印刷に適しているか評価し、自律的にアップスケールを実行できるようにします。

サーバーの起動

# Standalone entrypoint
upscalex-mcp

# Or via CLI
upscalex serve

クライアントの設定

方法 1：Pip を使用（pip install upscalex）

A. Claude Desktop

設定ファイルのパス：

• Windows：%APPDATA%\Claude\claude_desktop_config.json
• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "upscalex": {
      "command": "upscalex-mcp"
    }
  }
}

注：環境の PATH にグローバルな pip バイナリがない場合は、Python を明示的に指定してください。

{
  "mcpServers": {
    "upscalex": {
      "command": "python",
      "args": ["-m", "upscalex.server"]
    }
  }
}

B. デフォルト／一般的な MCP クライアント（Cursor、Antigravity、Windsurf、Claude Code）

設定ファイル：mcp_config.json または .cursor/mcp.json

{
  "mcpServers": {
    "upscalex": {
      "command": "upscalex-mcp"
    }
  }
}

---

方法 2：Git クローンとソースチェックアウトを使用

A. Claude Desktop（uv または virtualenv を使用）

{
  "mcpServers": {
    "upscalex": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/upscalex",
        "upscalex-mcp"
      ]
    }
  }
}

仮想環境を直接指定する方法（Windows／Linux／macOS）：

{
  "mcpServers": {
    "upscalex": {
      "command": "/absolute/path/to/upscalex/.venv/bin/python",
      "args": ["-m", "upscalex.server"]
    }
  }
}

（Windows では、C:\\absolute\\path\\to\\upscalex\\.venv\\Scripts\\python.exe を使用してください）

B. デフォルト／一般的な MCP クライアント（Cursor、Antigravity、Windsurf）

設定ファイル：mcp_config.json または .cursor/mcp.json

{
  "mcpServers": {
    "upscalex": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/upscalex",
        "upscalex-mcp"
      ]
    }
  }
}

ツールスキーマと JSON-RPC 契約の詳細については、MCP ガイドを参照してください。

---

モデルマトリックスとカタログ

UpscaleX は、あらかじめパッケージ化されたコアモデルと、必要に応じてダウンロードできるコミュニティモデルの両方をサポートしています。

モデル ID	拡大率	対象メディア	VRAM 要件	状態	説明
realesrgan-x4plus	4x	写真／ファインアート	中（4GB VRAM）	インストール済み	高品質な写真、アート、展示ポスター向けのフラッグシップモデルです。
realesrgan-x4plus-anime	4x	アニメ／イラスト	中（4GB VRAM）	インストール済み	2D イラストのフラットな色彩、シャープな輪郭、線の明瞭さを維持します。
realesr-animevideov3-x4	4x	動画／高速プレビュー	低（1GB-2GB／CPU）	インストール済み	高速処理と低スペックシステム向けの軽量な 4x フィードフォワードモデルです。
realesr-animevideov3-x2	2x	アニメーション／動画	低（1GB-2GB／CPU）	インストール済み	動画フレーム、アイコン、軽量なウェブアセット向けの高速な 2x モデルです。
realesr-animevideov3-x3	3x	アニメーション／動画	低（1GB-2GB／CPU）	インストール済み	中間的な拡大向けの高速な 3x モデルです。
realesr-general-x4v3	4x	汎用／コンパクト	低（2GB VRAM）	インストール済み	メモリ消費量の少ない、公式のコンパクトな汎用モデルです。
4x-ultrasharp	4x	ポートレート／超高精細	中～高（4GB-6GB）	ダウンロード可能	微細なテクスチャ、ポートレート、生地、肌の処理に優れたコミュニティ製モデルです。
4x-nmkd-superscale	4x	クリーンなフォトリアル画像	中～高（4GB-6GB）	ダウンロード可能	クリーンな写真で学習しており、髪、糸、葉の細部を維持します。
realesrgan-anime-6b	4x	アニメ／高速処理	低（1GB-2GB／CPU）	ダウンロード可能	高速処理向けの、軽量な 6 ブロックのアニメモデルです。

追加モデルのダウンロード

CLI または download_model MCP ツールからモデルをダウンロードできます。

# Download 4x UltraSharp for portraits
upscalex download-model 4x-ultrasharp

# Download NMKD clean photo model
upscalex download-model 4x-nmkd-superscale

---

テストと検証

テストスイートを実行して、モデルの解像度計算、CLI の終了コード、実際の GPU 推論を検証してください。

uv pip install -e ".[dev]"
uv run pytest -v

変更を提出する前に、すべてのテストに合格する必要があります。

---

コントリビューション

UpscaleX へのコントリビューションを歓迎します。コーディング規約、プルリクエストの手順、開発ガイドラインについては、CONTRIBUTING.md をお読みください。

---

ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。詳細は LICENSE ファイルをご覧ください。