squoosh-mcp

An MCP server that lets AI agents optimise images the way an expert would. It handles a whole folder at once, deciding format, size and quality separately for each image.

It uses the codecs and settings from Squoosh: WebP by default, plus AVIF, MozJPEG, OxiPNG and libimagequant on request. Each image gets the smallest file that still meets a visual-quality score, SSIMULACRA 2, so you aren't guessing a quality number.

Unofficial. Not affiliated with or endorsed by Google or the Squoosh team.

Why

squoosh.app gives great results, but you do one image at a time, by hand, in a browser. Squoosh's batch tools apply one setting to every image, which doesn't suit a mix of photos, screenshots, logos and odd aspect ratios. squoosh-mcp lets your agent do what you would do by hand, for every image:

Measured on 12 phone photos (1792×2400 PNG, 81 MB in total), Apple Silicon Mac. Every image scored 75–77 against a target of 75, and at 100% zoom they're hard to tell apart from the originals.

Related MCP server: obrobka-mcp

Install

You need Node.js 22.17 or newer. Give the server the folders it may read and write. It refuses everything else.

Claude Code

claude mcp add squoosh -- npx -y squoosh-mcp /absolute/path/to/images

Inside a project, you can leave the path out. The server then uses the project folder (CLAUDE_PROJECT_DIR), but never your home folder or a filesystem root.

Claude Desktop

Settings → Developer → Edit Config (claude_desktop_config.json):

{
  "mcpServers": {
    "squoosh": {
      "command": "npx",
      "args": ["-y", "squoosh-mcp", "/Users/you/Pictures/site-images"]
    }
  }
}

Cursor

.cursor/mcp.json in the project, or ~/.cursor/mcp.json:

{
  "mcpServers": {
    "squoosh": {
      "command": "npx",
      "args": ["-y", "squoosh-mcp", "${workspaceFolder}"]
    }
  }
}

VS Code

.vscode/mcp.json (note the servers key):

{
  "servers": {
    "squoosh": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "squoosh-mcp", "."]
    }
  }
}

Codex CLI

codex mcp add squoosh -- npx -y squoosh-mcp /absolute/path/to/images

The first npx download can take longer than Codex's default 10 s start-up limit. Raise it in ~/.codex/config.toml:

[mcp_servers.squoosh]
command = "npx"
args = ["-y", "squoosh-mcp", "/absolute/path/to/images"]
startup_timeout_sec = 30

Windsurf / Devin Desktop

Same shape as Claude Desktop, in ~/.codeium/windsurf/mcp_config.json (Windsurf) or ~/.config/devin/mcp_config.json (Devin Desktop).

Use

Ask your agent in plain words:

• "Optimise every image in public/images for the web."

• "Make the hero image responsive with srcset, and load it first."

• "Turn these product photos into 400×400 thumbnails."

• "Compress the screenshots in docs/ losslessly."

• "What would you do with assets/? Don't write anything yet."

The agent calls these tools:

Settings, at the top level or per file:

The balanced preset targets 75 for photos and 85 for screenshots, graphics and icons. The metric is tuned on photos and doesn't weigh faint 1-pixel UI lines heavily enough, so flat content gets a higher target.

Output

New files go to an optimized/ folder inside each input folder, mirroring its subfolders; you can set outputDir instead. Originals are never modified.

images/
  hero.jpg
  logo.png
  optimized/
    hero-1920w.webp  hero-1280w.webp  hero-640w.webp
    logo.webp
    squoosh-manifest.json   ← every output, its score, and ready-to-paste markup

Re-running skips images whose source and settings haven't changed. If a run is interrupted, the next run picks up where it stopped.

Supported formats

Not supported yet: HEIC, SVG, BMP and ICO are skipped with a reason. Animated PNG is left as it is.

Configuration

How it differs from Squoosh

squoosh-mcp runs Squoosh's codecs through sharp (libvips) with Squoosh's settings, plus OxiPNG. That makes it fast and native rather than browser WASM. Libraries can differ in version from squoosh.app's frozen 2024 build, so outputs are close to squoosh.app's but not byte-identical. The quality score is fast-ssim2, compiled to WebAssembly.

Development

npm install
npm run build        # TypeScript → dist/, plus the prebuilt SSIMULACRA 2 WASM
npm test             # unit and end-to-end tests (in-memory MCP client)
npm run fixtures     # edge-case test images → test/fixtures/generated/
npm run inspector    # try the tools in the MCP Inspector

See CONTRIBUTING.md.

License

Apache-2.0. Third-party components: THIRD_PARTY_NOTICES.md.