UpscaleX

[UpscaleX Banner]

UpscaleX MCP/CLI

[PyPI: Version] [License: MIT] [Python: 3.10+] [MCP: Enabled] [Acceleration: Vulkan GPU]

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.

Table of Contents

• 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]

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.gitcd upscalex
# Create virtual environment and install packageuv venvuv 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 entrypointupscalex-mcp
# Or via CLIupscalex 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:

Download Additional Models

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

# Download 4x UltraSharp for portraitsupscalex download-model 4x-ultrasharp
# Download NMKD clean photo modelupscalex 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.