VisionSqueezer

LLM-native image optimization middleware & MCP server. Reduces vision model token consumption by preprocessing images into tile-boundary-aligned, padding-free formats.

Works withany agent or editorthat speaks MCP — Claude, GPT, Gemini, Codex, or your own.

Picks the client, method, and scope for you:

- Target CLI — Claude Code / Codex CLI / Qwen Code / OpenCode / Gemini CLI / Kimi CLI
- Install method (Claude Code only) —plugin(bundles MCP + stats/doctor/upgrade skills) ormcp-add(server only)
- Install scope (mcp-addonly) —user(all projects, recommended),local(this project only),project(share via.mcp.json)

Scripted setups pass the choices directly:

npx vision-squeezer install --client claude --method plugin --yes npx vision-squeezer install --client claude --method mcp-add --scope user --yes

Claude Code — plugin marketplace (one-liner, bundles skills)

/plugin marketplace add eralpozcan/vision-squeezer /plugin install vision-squeezer-mcp@vision-squeezer

Installs the MCP serverand/vision-stats,/vision-doctor,/vision-upgradeskills as a single Claude Code plugin. Restart open Claude Code sessions for the MCP server to attach.

# All projects on this machine (recommended) claude mcp add --scope user vision-squeezer -- npx -y vision-squeezer # This project only (Claude Code's default) claude mcp add vision-squeezer -- npx -y vision-squeezer # Share with the team via .mcp.json in the repo claude mcp add --scope project vision-squeezer -- npx -y vision-squeezer

Add to~/.config/claude/claude_desktop_config.json:

{ "mcpServers": { "vision-squeezer": { "command": "npx", "args": ["-y", "vision-squeezer"] } } }

cursor --add-mcp '{"name":"vision-squeezer","type":"stdio","command":"npx","args":["-y","vision-squeezer"]}'

{ "servers": { "vision-squeezer": { "type": "stdio", "command": "npx", "args": ["-y", "vision-squeezer"] } } }

{ "servers": { "vision-squeezer": { "type": "stdio", "command": "npx", "args": ["-y", "vision-squeezer"] } } }

OpenTools → GitHub Copilot → Model Context Protocol (MCP) → Configure, then add:

{ "servers": { "vision-squeezer": { "command": "npx", "args": ["-y", "vision-squeezer"] } } }

Add to~/.codeium/windsurf/mcp_config.json:

{ "mcpServers": { "vision-squeezer": { "command": "npx", "args": ["-y", "vision-squeezer"] } } }

gemini mcp add --scope user vision-squeezer -- npx -y vision-squeezer

Or add to~/.gemini/settings.json(user) /.gemini/settings.json(project):

{ "mcpServers": { "vision-squeezer": { "command": "npx", "args": ["-y", "vision-squeezer"] } } }

codex mcp add vision-squeezer -- npx -y vision-squeezer

[mcp_servers.vision-squeezer] command = "npx" args = ["-y", "vision-squeezer"]

qwen mcp add vision-squeezer -- npx -y vision-squeezer

opencode mcp addis interactive-only, so add directly to~/.config/opencode/opencode.json(global) oropencode.jsonin the repo root (project):

{ "mcp": { "vision-squeezer": { "type": "local", "command": ["npx", "-y", "vision-squeezer"], "enabled": true } } }

kimi mcp add vision-squeezer -- npx -y vision-squeezer

{ "context_servers": { "vision-squeezer": { "command": "npx", "args": ["-y", "vision-squeezer"] } } }

Add to.kiro/settings/mcp.json(workspace) or~/.kiro/settings/mcp.json(global):

{ "mcpServers": { "vision-squeezer": { "command": "npx", "args": ["-y", "vision-squeezer"] } } }

MCP-only, no hooks needed. Configure via the Antigravity MCP settings:

{ "mcpServers": { "vision-squeezer": { "command": "npx", "args": ["-y", "vision-squeezer"] } } }

# From crates.io cargo install vision-squeezer # Or from source git clone https://github.com/eralpozcan/vision-squeezer && cd vision-squeezer make install # builds → ~/.local/bin/

Then use the binary path directly in any config above instead ofnpx:

{ "command": "vision-squeezer-mcp" }

Tip:Runnpx -y vision-squeezer --setupto print ready configs with auto-detected paths.

vision-squeezer path/to/image.jpg \ --mode auto|ocr|standard \ # default: auto (detects text/grayscale) --format jpeg|webp|avif \ # default: jpeg --quality 85 \ # output quality 1-100 (default: 75) --tile-size 256 \ # patch size in px (default: 512) --no-crop \ # disable padding removal --smart-crop \ # edge-energy crop (vs corner-tolerance) --auto-quality 0.95 \ # binary-search quality to hit SSIM target --bg-tolerance 25 \ # background detection 0-255 (default: 15) --model claude|gpt4o|gpt5|gemini|llama|qwen|deepseek \ # model-aware resizing --max-tiles 20 \ # hard cap on tile count --json \ # machine-readable JSON output --dry-run # run pipeline, skip disk write

vision-squeezer ./screenshots --recursive --output-dir ./optimized vision-squeezer ./screenshots --recursive --json > report.json

If you send raw images to an LLM, you are leaking tokens. Modern vision models do not care about your file size (MB/KB); they only care aboutpixel dimensions, but each provider calculates costs completely differently.vision-squeezersimulates these algorithms to find the mathematical minimum size that drops your token usage without losing visual context.

As of 2026 (Claude 3.5 / 4.5+), Anthropic uses anarea-based formula:Tokens ≈ (Width × Height) / 750. Every single pixel of solid background or padding costs you tokens.

- The Fix:vision-squeezeraggressively crops padding (removing solid color borders). A 1025×1025 screenshot shrinks just enough to drop from 1,400 tokens to 1,024 tokens (%26 savings).

2. GPT-4.5 / GPT-4o (Tiling & Short-side Scaling)

OpenAI scales your image to fit inside a 2048px box, then rescales it again so theshortest side is exactly 768px. Finally, it chops the image into a grid of512×512 tiles. Each tile costs 170 tokens.

- The Fix:If your image's shortest side ends up being 769px, OpenAI will spill over into an entirely new row of 512×512 tiles, doubling your cost.vision-squeezersimulates this exact math and snaps the image down by a few pixels so it fits perfectly into the minimum number of tiles.

Gemini uses a massive768×768 tilesystem (if the image is > 384px). Each tile is a flat 258 tokens.

- The Fix:An 800×600 image will trigger a 2×1 tile grid (1,032 tokens).vision-squeezersnaps it down slightly to fit exactly inside a 768×768 box, dropping the cost to 258 tokens (%75 savings).

Meta's Mllama vision tiles images on a560×560grid, capped at 4 tiles (~1601 tokens each).

- The Fix:A 2400×1670 screenshot trimmed to 2400×1200 drops from a 2×2 to a 2×1 canvas:6,404 → 3,202 tokens (−50%). (Llama 4 uses a different vision encoder and is not modeled.)

5. Qwen2-VL / 2.5-VL / 3-VL (28px Patch Grid)

Alibaba's Qwen-VL uses a28px effective grid(14px patch × 2×2 merge);tokens = (W/28)·(H/28)bounded to[4, 16384].

- The Fix:The patch is small, so area is the lever — a 1024×1024 image with its border stripped to 896×896 drops1,369 → 1,024 tokens (−25%).

SigLIP-384 + 2× pixel-shuffle gives 196 tokens/tile on a(m·384, n·384)canvas (m·n ≤ 9).

- The Fix:An 800×768 image snapped to 768×768 drops from 3×2 to 2×2 tiles:1,415 → 1,023 tokens (−28%). (Open weights — the win is local-inference context, not API billing.)

Full provider math, exact formulas, and cited sources:visionsqueezer.com/providers

Input image → crop_padding remove solid-color borders → calculate_optimal_dims snap to tile boundary (always down) → [enforce_max_tiles] optional tile budget cap → resize_exact Lanczos3 → [binarize] OCR mode only: Otsu threshold → JPEG/WebP encode configurable quality & format

VisionSqueezer is a performance-critical middleware. We chose Rust for three uncompromising reasons:

- Invisible Latency:Image processing should never be the bottleneck. Rust ensures that snapping, cropping, and encoding happen in milliseconds, making the optimization layer truly invisible to the developer's workflow.
- Minimal Footprint:As an MCP server running in the background of your IDE, VisionSqueezer is designed to be ultra-lightweight, consuming near-zero CPU and RAM when idle.
- Wasm-Ready:Rust's first-class support for WebAssembly allows us to bring the same high-performance optimization to the browser and the Edge (Cloudflare Workers), enabling client-side squeezing before the image even hits the network.

Case Study 1: Standard Image (istanbul.jpg)

To demonstrate the impact on standard images, here is the run on a 2400×1670 image (4 MP, 0.5 MB) across the three scenarios:

Example 1: Agnostic Optimization (Default)

When no target model is specified, Squeezer reduces the file size and mathematically optimizes boundaries to be generally efficient across all models.

Input: 2400×1670 (0.5 MB) Output: 2048×1536 (0.3 MB, JPG q75) File: 28.6% smaller ── Token Estimates ───────────────────────────────────────── Model Before After Saved ------------------------------------------ Claude 5344 4194 1150 (21.5%) GPT-4o 1105 765 340 (30.8%) GPT-5 1536 1536 0 (0.0%) Gemini 3096 1548 1548 (50.0%) ────────────────────────────────────────────────────────────

Example 2: Model-Targeted Optimization (GPT-4o)

If you tell Squeezer the target model, it reverses the model's exact internal calculation (e.g. GPT-4.5's 768px short-side scaling algorithm) and mathematically shrinks the image just enough to fit the absolute minimum tile grid.

vision-squeezer data/istanbul.jpg --model gpt4o

Input: 2400×1670 (0.5 MB) Output: 2399×1200 (0.3 MB, JPG q75) File: 33.6% smaller ── Token Estimates ───────────────────────────────────────── Model Before After Saved ------------------------------------------ Claude 5344 3838 1506 (28.2%) GPT-4o 1105 1105 0 (0.0%) GPT-5 1536 1536 0 (0.0%) Gemini 3096 2064 1032 (33.3%) ────────────────────────────────────────────────────────────

Notice how targetinggpt4operfectly fits the image into a solid 6-tile boundary (2399x1200) mathematically calculated backwards from OpenAI's short-side scaling algorithm. It maximizes resolution exactly up to the point where an extra tile would be billed.

Example 3: Model-Targeted Optimization (Claude)

Since Claude uses an area-based calculation (W × H / 750), Squeezer primarily focuses on aggressively cropping solid-color borders and padding to shrink the pixel area without drastically downscaling the core visual detail.

vision-squeezer data/istanbul.jpg --model claude

Input: 2400×1670 (0.5 MB) Output: 2304×1536 (0.4 MB, JPG q75) File: 21.3% smaller ── Token Estimates ───────────────────────────────────────── Model Before After Saved ------------------------------------------ Claude 5344 4718 626 (11.7%) GPT-4o 1105 1105 0 (0.0%) GPT-5 1536 1536 0 (0.0%) Gemini 3096 1548 1548 (50.0%) ────────────────────────────────────────────────────────────

Claude benefits tremendously from even minor dimension reductions. By snapping the width and height slightly downwards, we immediately shaved off over 600 tokens while preserving the massive 2304×1536 resolution.

Case Study 2: 12-Megapixel High-Res Image (istanbul2.jpg)

To demonstrate the impact on massive images, here is the run on a 4096×3072 image (12 MP, 2.2 MB) across the three scenarios:

Input: 4096×3072 (2.2 MB) Output: 3584×2560 (1.3 MB, JPG q75) File: 39.6% smaller ── Token Estimates ───────────────────────────────────────── Model Before After Saved ------------------------------------------ Claude 16777 12233 4544 (27.1%) GPT-4o 765 1105 0 (0.0%) GPT-5 1536 1536 0 (0.0%) Gemini 6192 5160 1032 (16.7%) ────────────────────────────────────────────────────────────

(Notice theOpenAI Aspect Ratio Anomaly: Squeezer removed heavy letterboxing (padding) from this image. By removing the padding, the image became "wider". Because OpenAI's API forces thenewshort side to 768px, the wide aspect ratio pushed the long side into a 3rd tile grid column! This is a fascinating edge case where cropping padding mathematically INCREASES your GPT-4o token cost. If you specifically use--model gpt4oon this image, Squeezer will detect this paradox and use a different grid constraint).

Example 2: Model-Targeted Optimization (GPT-4o)

vision-squeezer data/istanbul2.jpg --model gpt4o