UpscaleX MCP/CLI

UpscaleX is a production-grade 8K and 16K image upscaler CLI and Model Context Protocol (MCP) server powered by RealESRGAN, Vulkan GPU hardware acceleration, and Lanczos supersampling.

Engineered for digital print workflows, large-format poster production, fine art reproductions, and autonomous AI coding agents in Claude Desktop, Antigravity, and Cursor.

Looking for quick setup? Read the Installation Guide for a copy-paste AI Agent setup prompt and manual instructions, or provide your AI coding assistant with the UpscaleX Agent Skill.

Key Features
Installation Guide
AI Agent Skill
Visual Quality Comparison
Documentation Directory
Quickstart with uv
Command-Line Interface
Model Context Protocol (MCP) Integration
Model Matrix
Testing and Verification
Contributing
License

Key Features

Dual-Mode Operation: Interactive command-line interface (upscalex) and standard Model Context Protocol server (upscalex-mcp).
8K and 16K Presets:
- 16K: Native 4x RealESRGAN deep-learning model upscale producing master files up to 400+ Megapixels.
- 8K: 4x deep-learning inference followed by Lanczos-3 downsampling (Supersampling Anti-Aliasing / SSAA) for sharp edges and zero noise.
- Custom Dimensions: Proportional scaling to arbitrary resolutions or physical print aspect ratios.
Cross-Platform Architecture: Tested and supported across Windows, Linux (Ubuntu, Debian, Fedora), and macOS (Apple Silicon arm64 & Intel x86_64).
GPU Acceleration with Seamless CPU Fallback: Automatically discovers and utilizes discrete Vulkan GPUs (NVIDIA RTX/GeForce, AMD Radeon, Intel Arc/Iris, Apple Silicon via MoltenVK). In headless Docker containers or environments without GPU drivers, the engine falls back to multi-threaded CPU Lanczos super-resolution with zero crashes.
Hardware Diagnostics: Integrated upscalex doctor command inspects system compute devices, Vulkan support, and recommended tile dimensions.
Memory-Safe Tiling: Sliding-window spatial tile decomposition (--tile-size 256) processes ultra-gigapixel images without Out-Of-Memory (OOM) failures on 4GB to 8GB GPUs.
Automated Engine Provisioning: Downloads and validates the precompiled platform binary automatically if not found locally.
Print Fidelity Analysis: Automatically calculates physical print dimensions in inches and centimeters at 300 DPI, 150 DPI, and 72 DPI.

Visual Quality Comparison

Below is an empirical comparison demonstrating UpscaleX 4x super-resolution reconstruction on a low-resolution pixelated source (663 × 531 px, 0.35 MP) upscaled to high-definition print fidelity (2,652 × 2,124 px, 5.63 MP) using the realesrgan-x4plus model.

UpscaleX Quality Comparison

Metric	Original Source	UpscaleX 4x Output
Pixel Dimensions	`663 × 531`	`2,652 × 2,124`
Total Megapixels	0.35 MP	5.63 MP (16× Pixel Multiplication)
Edge Reconstruction	Heavy block pixelation, ringing	Reconstructed circular spokes, sharp contours
Max 300 DPI Print Size	2.2 × 1.8 inches	8.8 × 7.1 inches
Model	—	`realesrgan-x4plus`
Hardware	—	NVIDIA GeForce RTX 3050 Laptop GPU (10.8s)

Documentation Directory

Comprehensive technical guides are available in the docs/ directory and repository root:

Installation Guide: AI Agent autonomous copy-paste prompt and manual installation procedures.
AI Agent Skill Specification: Standard agent skill definition for Claude, Cursor, and Antigravity.
CLI Reference Guide: Complete flag documentation, tiling strategies, and execution examples.
Model Context Protocol (MCP) Guide: JSON-RPC tool contracts, parameter schemas, and multi-client configuration.
Architecture & Mathematics Specification: Deep-learning foundations, RRDB networks, Lanczos kernels, and memory bounds.
Error Handling & Troubleshooting: Known failure modes, pre-flight sanitization, and recovery procedures.
Contributing Guide: Code standards, test procedures, and pull request workflow.

Quickstart

Option 1: Install from PyPI (Simplest for CLI & MCP)

pip install upscalex

Option 2: Clone and Install from Source (with 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 .

Inspect Available Models

upscalex models

Command-Line Interface

16K Upscale (Default 4x Model)

upscalex upscale input.png --target 16k

8K Supersampled Upscale

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

2D Illustration / Anime Artwork

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

Image and Print Sizing Inspection

upscalex info input.png

Hardware and Content-Aware Model Recommendation

upscalex recommend input.png

For complete options and arguments, see the CLI Guide.

Model Context Protocol (MCP) Integration

UpscaleX runs as a native MCP server over stdio, enabling AI agents (Claude Desktop, Cursor, Antigravity, Windsurf, Zed) to inspect image metadata, evaluate print viability, and execute upscaling autonomously.

Server Invocation

# Standalone entrypoint
upscalex-mcp

# Or via CLI
upscalex serve

Client Configuration

Method 1: Using Pip (`pip install upscalex`)

A. Claude Desktop

Configuration file paths:

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"
    }
  }
}

Note: If your environment does not have global pip binaries in PATH, use explicit Python:

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

B. Default / Common MCP Clients (Cursor, Antigravity, Windsurf, Claude Code)

Configuration file: mcp_config.json or .cursor/mcp.json

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

Method 2: Using Git Clone & Source Checkout

A. Claude Desktop (with uv or virtualenv)

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

Direct virtual environment alternative (Windows / Linux / macOS):

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

(On Windows, use C:\\absolute\\path\\to\\upscalex\\.venv\\Scripts\\python.exe)

B. Default / Common MCP Clients (Cursor, Antigravity, Windsurf)

Configuration file: mcp_config.json or .cursor/mcp.json

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

For complete tool schemas and JSON-RPC contracts, see the MCP Guide.

Model Matrix and Catalog

UpscaleX supports both pre-packaged core models and on-demand downloadable community models:

Model ID	Scale	Target Media	VRAM Requirement	Status	Description
`realesrgan-x4plus`	4x	Photos / Fine Art	Medium (4GB VRAM)	Installed	Flagship model for high-fidelity photography, art, and exhibition posters.
`realesrgan-x4plus-anime`	4x	Anime / Illustration	Medium (4GB VRAM)	Installed	Preserves flat colors, sharp contours, and line definition in 2D illustrations.
`realesr-animevideov3-x4`	4x	Video / Fast Previews	Low (1GB-2GB / CPU)	Installed	Lightweight 4x feed-forward model for fast turnaround and low-spec systems.
`realesr-animevideov3-x2`	2x	Animation / Video	Low (1GB-2GB / CPU)	Installed	Fast 2x model for video frames, icons, and lightweight web assets.
`realesr-animevideov3-x3`	3x	Animation / Video	Low (1GB-2GB / CPU)	Installed	Fast 3x model for intermediate scaling.
`realesr-general-x4v3`	4x	General / Compact	Low (2GB VRAM)	Installed	Official compact general model with low memory consumption.
`4x-ultrasharp`	4x	Portraits / Ultra-Detail	Medium-High (4GB-6GB)	Downloadable	Community champion for micro-textures, portraits, fabrics, and skin.
`4x-nmkd-superscale`	4x	Clean Photorealistic	Medium-High (4GB-6GB)	Downloadable	Trained on clean photography; preserves hair, threads, and foliage.
`realesrgan-anime-6b`	4x	Anime / Fast	Low (1GB-2GB / CPU)	Downloadable	6-block lightweight anime model for rapid processing.

Download Additional Models

Download models through the CLI or via the download_model MCP tool:

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

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

Testing and Verification

Run the test suite to verify model resolution calculation, CLI exit codes, and live GPU inference:

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

All tests must pass prior to submitting changes.

Contributing

Contributions to UpscaleX are welcome. Please read CONTRIBUTING.md for coding standards, pull request processes, and development guidelines.

License

This project is licensed under the MIT License. See the LICENSE file for details.

upscalex

Documentation