MCP Setup
VisionSqueezer ships an MCP (Model Context Protocol) server that exposes image optimization as a tool your AI agent can call. Thanks to npx -y, no global install is required.
The server applies a 1600-token budget by default, see the token budget guide.
One command
Pick your client and run the line. Each one registers the server for you.
| Client | Command |
|---|---|
| Claude Code | npx vision-squeezer install --client claude --scope user --yes (plugin: MCP server, skills, image-read hook) |
| Codex CLI | codex mcp add vision-squeezer -- npx -y vision-squeezer |
| Gemini CLI | gemini mcp add --scope user vision-squeezer -- npx -y vision-squeezer |
| Qwen Code | qwen mcp add vision-squeezer -- npx -y vision-squeezer |
| Kimi CLI | kimi mcp add vision-squeezer -- npx -y vision-squeezer |
| VS Code | code --add-mcp '{"name":"vision-squeezer","command":"npx","args":["-y","vision-squeezer"]}' |
| Cursor | npx vision-squeezer install --client cursor --yes |
| Windsurf | npx vision-squeezer install --client windsurf --yes |
| Claude Desktop | npx vision-squeezer install --client claude-desktop --yes |
| OpenCode | npx vision-squeezer install --client opencode --yes |
The code --add-mcp line adds the server to your VS Code user profile and works in macOS and Linux shells. On PowerShell, escape the quotes as in the VS Code docs.
The Claude Code, Cursor, Gemini CLI, and OpenCode installs also add an image-read hook, so images the agent reads from your project are swapped for the optimized copy. See which clients get the hook.
Installer
Every client has one install path and the installer picks it. It pins the version and handles scope for Claude Code, Codex, Qwen, OpenCode, Gemini, Kimi, Cursor, Windsurf, Claude Desktop, and VS Code. For Cursor, Windsurf, Claude Desktop, and OpenCode it merges one entry into the JSON config: your other servers are kept, and a file it cannot parse (for example one with comments) is left untouched.
npx vision-squeezer install # interactive
npx vision-squeezer install --client codex --yes # scripted
npx vision-squeezer install --client claude --scope user --yes # plugin: MCP + skills + image-read hook
Manual configuration
Prefer editing the file yourself, or use Zed (not in the installer: its settings.json allows comments)? Add one entry and restart the editor.
Add to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (this project):
{
"mcpServers": {
"vision-squeezer": {
"command": "npx",
"args": ["-y", "vision-squeezer"]
}
}
}
Prefer the code --add-mcp line above. To share the server with your team, commit a .mcp.json at the project root:
{
"mcpServers": {
"vision-squeezer": {
"command": "npx",
"args": ["-y", "vision-squeezer"]
}
}
}
Or run MCP: Add Server from the Command Palette.
In the Cascade panel, open the ... menu and choose Open MCP config file (usually ~/.codeium/windsurf/mcp_config.json), then add:
{
"mcpServers": {
"vision-squeezer": {
"command": "npx",
"args": ["-y", "vision-squeezer"]
}
}
}
This applies to the Cascade agent. Windsurf's Devin Local agent reads the Devin CLI config instead.
Open Settings → AI → MCP Servers → Add Server, or run zed: open settings file and add:
{
"context_servers": {
"vision-squeezer": {
"command": "npx",
"args": ["-y", "vision-squeezer"]
}
}
}
Add to claude_desktop_config.json:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"vision-squeezer": {
"command": "npx",
"args": ["-y", "vision-squeezer"]
}
}
}
opencode mcp add is interactive-only, so use npx vision-squeezer install --client opencode --yes, or add to ~/.config/opencode/opencode.json:
{
"mcp": {
"vision-squeezer": {
"type": "local",
"command": ["npx", "-y", "vision-squeezer"],
"enabled": true
}
}
}
Add to ~/.codex/config.toml:
[mcp_servers.vision-squeezer]
command = "npx"
args = ["-y", "vision-squeezer"]
More editors (JetBrains, Kiro, Antigravity) are listed in the README.
MCP tools
Once registered, the server exposes three tools:
| Tool | Purpose | Key args |
|---|---|---|
optimize_image | Standard optimization. Returns the optimized image plus a short JSON report | image_path (preferred) or image_base64, target_model (core profiles plus kimi, glm, pixtral, gemma, internvl, llava, minimax, and other catalog aliases), max_tokens (token budget, default 1600, 0 disables), mode (standard / ocr / auto; only ocr drops colour), output_format (jpeg / webp / avif) |
sandbox_execute | Think-in-Code: run atomic ops locally | operations[] — crop, grayscale, binarize, resize, contrast, brightness |
get_savings_stats | Cumulative token / USD savings | — |
npx -y vision-squeezer@X.Y.Z, or @latest) in shared configs: an unpinned npx cache can freeze users on whatever tarball resolved first. The installer pins for you.Verify
Restart the client, then ask it to list its MCP tools. You should see optimize_image, sandbox_execute, and get_savings_stats. To check the package itself:
npx -y vision-squeezer --version
If the MCP server fails to connect, run vision-doctor (Claude Code skill) — it probes the registered command and surfaces the root cause.