Ruah MCP Server

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

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

Or as a plugin, which adds a short skill on chaining the tools:

claude plugin marketplace add 0-big/ruah-mcp
claude plugin install ruah@ruah-tools

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.

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.

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. packages/ruah-mcp/plugin is the Claude Code plugin, listed by .claude-plugin/marketplace.json.

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.