Vision Squeezer

VisionSqueezer

Fit images to a vision-LLM token budget before they reach the model. A library, CLI, and MCP server for code, agents, and pipelines.

What it does not do. VisionSqueezer cannot shrink an image you paste, drag, or @-attach into a chat window (Claude Code, Cursor, ChatGPT, and so on). The client attaches it before any tool or hook runs, so it is billed at full size.

Where it does save tokens:

- Images your code sends to a model API: the Rust crate, the Python bindings, the CLI.

- Images an agent reads from files or gets through tools (screenshots, crawlers, browser automation): the MCP server, or the Claude Code image-read hook for files inside the project.

See Where it saves tokens for the exact cases.

The MCP server runs in any MCP client (Claude Code, Cursor, Codex, Gemini CLI, and others), but it only sees images the agent passes to it.

---

Install

One command per client (recommended)

npx vision-squeezer install                       # asks for the client and scope

npx vision-squeezer install --client claude --scope user --yes npx vision-squeezer install --client cursor --yes

Every client has exactly one install path, and the installer picks it:

JSON files are merged, never replaced: other servers and hooks are kept, a file that cannot be parsed is left untouched, and re-running replaces our own entry instead of adding a second.

The scope (user, local, project) is asked only when the client supports more than one. --method from older versions is accepted and ignored.

The manual commands below use npx -y vision-squeezer for brevity. Pin it as vision-squeezer@ (the installer does this for you): an unpinned npx keeps serving whatever version it cached first, even after a new release.

Claude Code

npx vision-squeezer install --client claude --scope user --yes

This runs the two commands below for you (and removes an older claude mcp add registration and settings.json hook first). To do it by hand:

claude plugin marketplace add eralpozcan/vision-squeezer

claude plugin install vision-squeezer-mcp@vision-squeezer --scope user

Restart Claude Code, or run /reload-plugins, to load the MCP server, skills, and hook. Only want the MCP server, with no skills and no hook? claude mcp add --scope user vision-squeezer -- npx -y vision-squeezer.

Claude Desktop

npx vision-squeezer install --client claude-desktop --yes

Or add to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\\Claude\\):

{

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

Cursor

npx vision-squeezer install --client cursor --yes

Or add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project):

{

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

Click here to view installation instructions for 10+ other IDEs and Agents (VS Code, JetBrains, Windsurf, Zed, etc.)

VS Code Copilot

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

Or add to .vscode/mcp.json:

{

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

JetBrains (IntelliJ, WebStorm, PyCharm)

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

{

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

Windsurf

npx vision-squeezer install --client windsurf --yes

Or add to ~/.codeium/windsurf/mcp_config.json:

{

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

Gemini CLI

Google replaced Gemini CLI with Antigravity CLI for free and Google One users on 2026-06-18. On Antigravity, see Antigravity.

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 CLI

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

Or add to ~/.codex/config.toml:

[mcp_servers.vision-squeezer]

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

Qwen Code

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

OpenCode

opencode mcp add is interactive-only, so add directly to ~/.config/opencode/opencode.json (global) or opencode.json in the repo root (project):

{

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

Kimi CLI

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

Zed

Add to ~/.config/zed/settings.json:

{

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

Kiro

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

{

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

Antigravity

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

{

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

Manual install (Rust binary)

# 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 of npx:

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

Tip: Run npx -y vision-squeezer --setup to print ready configs with auto-detected paths.

---

CLI Usage

vision-squeezer path/to/image.jpg \

--mode auto|ocr|standard \ # default: auto (= standard, keeps colour; ocr is opt-in) --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 \ # model-aware resizing; see the model catalog --max-tokens 1600 \ # token budget: downscale until the output fits (0 = off; MCP default 1600) --max-tiles 20 \ # hard cap on tile count (model-specific unit) --json \ # machine-readable JSON output --dry-run # run pipeline, skip disk write

Batch mode

Pass a directory instead of a file:

vision-squeezer ./screenshots --recursive --output-dir ./optimized

vision-squeezer ./screenshots --recursive --json > report.json

HTTP API (n8n, Make, Zapier)

vision-squeezer serve runs a small HTTP server, so any workflow tool can squeeze an image between two steps with a plain HTTP request. No custom node is needed.

vision-squeezer serve                    # 127.0.0.1:8080

docker build -t vision-squeezer . # or run it in a container docker run -p 8080:8080 vision-squeezer

Send the image bytes as the body of POST /optimize. Options go in the query string:

curl --data-binary @screenshot.png "http://localhost:8080/optimize?max_tokens=1600" -o out.jpg -D -

X-Tokens-Before: 4674

X-Tokens-After: 1584

X-Input-Size: 2400x1670

X-Output-Size: 1344x924

GET /health returns ok. Bodies over 25 MB get 413, bad input gets 400 with a one-line reason. There is no authentication: the server listens on 127.0.0.1 by default, and the Docker image listens on all interfaces inside the container, so publish its port only on a network you trust.

n8n. Put an HTTP Request node between the step that fetches the image and the vision model:

• Method POST, URL http://vision-squeezer:8080/optimize?max_tokens=1600 (the container name when both run on one Docker network, localhost otherwise).
• Send Body on, Body Content Type n8n Binary File, Input Data Field Name data.
• Options → Response → Response Format File, so the next node gets the optimized image as binary. Turn on Include Response Headers and Status to read the X-Tokens-* values.

These settings follow n8n's documentation and have not been tested in n8n itself yet.

---

The Math: How Vision Models Bill You in 2026

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 about pixel dimensions, but each provider calculates costs completely differently. vision-squeezer simulates these algorithms to find the mathematical minimum size that drops your token usage without losing visual context.

1. OpenAI GPT-6 / GPT-5.6 (32px Patches)

Current OpenAI vision models count 32×32 patches, fit high-detail images within a 2048px edge and 2500-patch budget, then apply a 1.2 multiplier.

• The Fix: --model gpt6 removes padding, fits the patch budget, and avoids partially used edge patches. A 1024×1024 input is 1024 patches / 1229 tokens.

2. Claude 4.7+ (28px Patches)

Claude counts `ceil(Width/28) × ceil(Heig