🎬 Topaz Video AI MCP Server

The Model Context Protocol (MCP) Server for Photorealistic AI Video Upscaling & Autonomous Enhancement

Empower AI Coding Assistants & Agents (Claude Desktop, Cursor, Antigravity, Windsurf) to analyze frames, auto-detect faces, choose optimal AI models (Iris v2 / Proteus v4), and upscale videos with 100% realistic, non-plastic textures.

# Quick Setup for Claude, Cursor, Antigravity, or Any MCP Client
git clone https://github.com/dannymaaz/topaz-video-ai-mcp.git
cd topaz-video-ai-mcp
pip install -e .

🌟 Overview

Topaz Video AI MCP Server connects Large Language Models (LLMs) and autonomous coding agents directly to the state-of-the-art Topaz Video AI engine.

Instead of opening the desktop app and guessing dials manually, your AI agent can now:

1. Inspect Video Frames: Extract keyframes and analyze resolution, blur, noise, and face presence using computer vision.

2. Apply Smart Resolution Rules: Automatically trigger 2x upscale for sub-1080p clips (< 1080p), or 1x Enhance mode for clips that are already 1080p+ (avoiding artificial overscaling).

3. Select the Right Neural Network: Automatically select Iris v2 when human faces are present, or Proteus v4 for high-speed scenery/general footage.

4. Guarantee Photorealism (Anti-Plastic): Prevent the notorious "waxy doll" or "CGI plastic face" look with calibrated original texture blending (blend=0.25) and micrograin injection.

5. Headless & Background Execution: No need to keep the Topaz GUI open. Renders run asynchronously via Topaz's custom hardware-accelerated FFmpeg pipeline (tvai_up).

Related MCP server: cutroom

🎨 The Anti-Plastic Philosophy

Most AI video upscalers produce smooth, artificial results where human skin looks like melted wax or plastic mannequin dolls.

Topaz Video AI MCP enforces strict cinema-grade photorealism parameters:

⚙️ Architecture Workflow

flowchart TD
    A["🎬 Input Video File"] --> B["🔍 topaz_analyze_video"]
    B --> C{"Visual Analysis"}
    
    C -->|"Resolution < 1080p"| D["📐 Auto 2x Upscale (Lanczos)"]
    C -->|"Resolution >= 1080p"| E["✨ 1x Enhance (No Upscaling)"]
    
    C -->|"Faces Detected"| F["👤 Iris v2 / v3 (Face Restoration)"]
    C -->|"Scenery / No Faces"| G["⚡ Proteus v4 / Nyx v2"]
    
    D & E & F & G --> H["🎨 Anti-Plastic Preset Engine"]
    H -->|"blend=0.25 | grain=0.018 | noise=0.03"| I["⏱️ topaz_estimate_render_time"]
    
    I --> J["🔬 topaz_preview_enhance (2-5s Sample)"]
    J --> K{"User Approval"}
    
    K -->|"Confirmed"| L["🚀 topaz_enhance_video (Background Job)"]
    L --> M["📊 topaz_get_job_status (% ETA FPS)"]
    M --> N["🎉 Pristine Enhanced Video Saved"]

🛠️ MCP Tool Catalog

📦 Installation & Setup

Prerequisites

1. Topaz Video AI (v5.x or v6.x) installed on your machine.

   • Standard Windows Path: C:\Program Files\Topaz Labs LLC\Topaz Video AI

   • Standard macOS Path: /Applications/Topaz Video AI.app/Contents/MacOS

   • (Optional) Set TOPAZ_APP_DIR environment variable if installed in a custom location.

2. Python 3.10+ installed on your system.

Option 1: Install via Git (Recommended)

git clone https://github.com/dannymaaz/topaz-video-ai-mcp.git
cd topaz-video-ai-mcp
pip install -e .

Option 2: Run directly with uv (Zero-Install)

uvx --from git+https://github.com/dannymaaz/topaz-video-ai-mcp.git topaz-video-ai-mcp

🔌 Agent Configurations

1. Claude Desktop

Add to your claude_desktop_config.json (%APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "topaz-video-ai": {
      "command": "python",
      "args": ["-m", "topaz_video_ai_mcp"],
      "env": {
        "TVAI_MODEL_DIR": "C:\\ProgramData\\Topaz Labs LLC\\Topaz Video AI\\models",
        "TVAI_MODEL_DATA_DIR": "C:\\ProgramData\\Topaz Labs LLC\\Topaz Video AI\\models"
      }
    }
  }
}

2. Cursor IDE

Add to .cursor/mcp.json or Global Cursor Settings:

{
  "mcpServers": {
    "topaz-video-ai": {
      "command": "python",
      "args": ["-m", "topaz_video_ai_mcp"]
    }
  }
}

3. Google Antigravity / Gemini CLI

Add to ~/.gemini/config/mcp_config.json:

{
  "mcpServers": {
    "topaz-video-ai": {
      "command": "python",
      "args": ["-m", "topaz_video_ai_mcp"],
      "env": {
        "TVAI_MODEL_DIR": "C:\\ProgramData\\Topaz Labs LLC\\Topaz Video AI\\models",
        "TVAI_MODEL_DATA_DIR": "C:\\ProgramData\\Topaz Labs LLC\\Topaz Video AI\\models"
      }
    }
  }
}

💡 Example Agent Prompts

Once configured, simply chat with your AI agent:

• "Analiza este video en C:\Videos\clip.mp4 y dime qué modelo de Topaz recomiendas y cuánto tardará."

• "Genera una muestra de 3 segundos del segundo 10 del video para revisar si la piel se ve realista."

• "Procesa el video completo en segundo plano escalándolo a x2 con Iris v2 y guárdalo en mi carpeta de salida."

• "Genera una imagen comparativa de Antes y Después en el segundo 5 del video renderizado."

• "Consulta el progreso y el tiempo restante del trabajo de Topaz."

❓ Frequently Asked Questions (FAQ)

Do I need to keep the Topaz Video AI desktop application open?

No. The MCP server interfaces directly with Topaz's underlying headless AI engine and custom FFmpeg binary (tvai_up). Topaz does not need to be open in the taskbar or desktop.

What hardware acceleration is used?

The engine automatically leverages hardware acceleration:

• Intel Graphics / CPUs: Intel Quick Sync Video (h264_qsv / hevc_qsv)

• NVIDIA GPUs: NVIDIA NVENC (h264_nvenc / hevc_nvenc)

• DirectML / OpenVINO: Utilized by Topaz's internal neural tensor runtimes.

How does it handle audio?

Audio tracks are passed through with bit-for-bit lossless copying (-c:a copy), ensuring audio never loses synchronization or fidelity.

What if my video is already 1080p or 4K?

The MCP automatically detects this and sets 1x Enhance mode instead of upscaling. This cleans up compression macroblocking and restores sharpness without creating blurry, bloated resolutions.

📈 Benchmarks (Real-World Reference)

Tested on Intel Iris Xe Graphics with 1080p / 720p footage:

🤝 Contributing & License

Contributions, feature requests, and pull requests are warmly welcomed! Please feel free to open an issue or submit a PR.

Released under the MIT License. Copyright © 2026 Topaz Video AI MCP Contributors.