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.
Install
Requires Node.js 20 or newer.
Claude Code
Or as a plugin, which adds a short skill on chaining the tools:
Any other MCP client (Claude Desktop, Cursor, …): add this to its MCP server config.
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.
Installing is separate: npx fetches the package and its dependencies from npm, and on Linux x64 the install script of onnxruntime-node (the AI runtime) also fetches about 260 MB of CUDA and TensorRT files from NuGet, which Ruah never uses. Set ONNXRUNTIME_NODE_INSTALL=skip in the server's environment to leave them out (the Claude Code plugin does).
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 2.4.1, its last
BSD-licensed release, compiled to WebAssembly and bundled in dist/index.js. Its notice is
dist/LICENSE-libimagequant.txt.