ruah-mcp

Image tools for AI agents, as an MCP server. Background removal, compression, resizing, cropping, AI upscaling and metadata removal all run on your own computer. Images never leave it.

It is the engine of ruah.tools: the same models, encoders and settings, packaged for an agent to call.

Tools

Files in, files out: every tool writes a new file next to the original (or to the path you give) and returns its path with a small preview. Existing files, the original included, are never overwritten. Images up to 12000×12000 pixels (144 MP) and 512 MB are accepted; upscale results are capped at 4096×4096.

Related MCP server: roundcut-mcp

Install

Requires Node.js 20 or newer.

Claude Code

claude mcp add ruah -- npx -y ruah-mcp

Any other MCP client (Claude Desktop, Cursor, …): add this to its MCP server config.

{
  "mcpServers": {
    "ruah": {
      "command": "npx",
      "args": ["-y", "ruah-mcp"]
    }
  }
}

Then ask your agent things like "remove the background from ~/Desktop/shoe.jpg" or "convert these screenshots to WebP".

What goes over the network

Only the AI model weights, once, from Ruah's model mirror (models.ruah.tools). Each file is checked against a SHA-256 hash pinned in this package before it is used, then kept in a local cache:

Compression, resizing, cropping and metadata removal need no download at all.

The cache lives in ~/.cache/ruah/models (or $XDG_CACHE_HOME/ruah/models). Set RUAH_CACHE_DIR to put it elsewhere.

Platforms

• macOS (Apple Silicon): tested. Upscaling runs on the GPU (WebGPU via Metal) and falls back to the CPU if that fails.

• Linux, Windows: upscaling runs on the CPU. The full test suite runs on both (x64) for every change; arm64 builds exist but are untested.

• Intel Macs are not supported: the ONNX runtime the AI tools run on ships no build for them.

• HEIC (iPhone photos) can be read on macOS only. HEVC is a patent-licensed codec and only macOS provides one here.

Licenses

ruah-mcp is MIT licensed (see LICENSE). The models it downloads keep their own licenses: BiRefNet (MIT) and Swin2SR (Apache-2.0). Lossy PNG compression uses libimagequant through the imagequant package, which is GPL-3.0 licensed and installed by npm as a separate dependency.

This repository

The source the npm package is built from, mirrored from Ruah's main repository. packages/ruah-mcp is the server; src/lib holds the image modules it shares with ruah.tools, kept at the same paths so the imports read the same here. The root package.json only installs what src/lib imports, for the tests and the type check.

npm ci
cd packages/ruah-mcp && npm ci && npm test

Issues and pull requests are welcome. Accepted changes are made in the main repository and arrive here with the next sync.