# Ruah

> Ruah is an open-source MCP server for design and media. On-device image tools for agents: cutouts, compress, resize, crop, upscale, EXIF removal. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, macOS, Windows, Linux
- **Website:** https://ruah.tools
- **Repository:** https://github.com/0-big/ruah-mcp/tree/HEAD/packages/ruah-mcp
- **MCP Registry name:** tools.ruah/ruah-mcp
- **Categories:** design and media, files and documents
- **Listing updated:** 2026-11-14

## About

Files stay on your computer. The server runs AI models and encoders locally, writing each result as a new file beside the original and returning its path with a small preview; existing files are never overwritten. Only model weights are downloaded, once, from Ruah's mirror, each checked against a pinned SHA-256 hash and cached in ~/.cache/ruah/models.

Background removal uses BiRefNet, with a lite 98 MB model fetched first and a larger one used only if no subject is found; upscaling uses Swin2SR at 2x or 4x. Compression, resizing, cropping and metadata removal need no download. Metadata removal strips EXIF (including GPS), XMP, IPTC and comments, and JPEG and PNG are cleaned without re-encoding.

It needs Node.js 20 or newer. Apple Silicon Macs are tested and use the GPU for upscaling; Linux and Windows use the CPU, and Intel Macs are not supported. HEIC input works only on macOS. The package is MIT licensed and is the engine behind the ruah.tools web app.

## Features

- **Background removal:** Cuts out the main subject and saves a transparent PNG.
- **Compress and convert:** Shrinks images or converts to WebP, AVIF, JPEG or PNG.
- **Resize and crop:** Resize by longest side or percent, or crop to a ratio or region without resampling.
- **AI upscaling:** Enlarge 2x or 4x while keeping transparency.
- **Metadata stripping:** Remove EXIF, XMP, IPTC, comments and embedded thumbnails.
- **Non-destructive output:** Writes new files and never overwrites the original.

## Good for

- Prepare product photos with transparent backgrounds
- Convert screenshots to WebP in a batch
- Strip GPS location from photos before sharing
- Upscale a small image by 2x or 4x
- Shrink image weight before a site release

## Install

### Claude Code (Terminal)

```sh
claude mcp add ruah-mcp -- npx -y ruah-mcp
```

### Claude Desktop (claude_desktop_config.json)

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

### Cursor (~/.cursor/mcp.json)

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

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "ruah-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "ruah-mcp"
      ]
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

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

### Other clients (your client's MCP settings (most use this shape))

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

## Tools

- `remove_background`: Cuts the main subject out of a photo and saves a transparent PNG.
- `compress`: Makes an image smaller or converts it to WebP, AVIF, JPEG or PNG.
- `resize`: Changes pixel dimensions while keeping proportions.
- `crop`: Crops to an aspect ratio or region, rotates by quarter turns and flips.
- `upscale`: Enlarges an image 2x or 4x with AI super-resolution.
- `strip_metadata`: Removes EXIF, XMP, IPTC, comments and embedded thumbnails.

## FAQ

### Do my images leave my computer?

No. Processing runs locally; only model weights are downloaded, once.

### Which Node.js version is needed?

Node.js 20 or newer.

### Does it work on Intel Macs?

No. The ONNX runtime it uses ships no build for them.

### Can it read iPhone HEIC photos?

Only on macOS, because HEVC decoding is available only there.

### What licence applies?

ruah-mcp is MIT licensed; the downloaded models keep their own licences (BiRefNet MIT, Swin2SR Apache-2.0).

### Is Ruah free?

Yes. Ruah is open source, so you can use and self-host it for free.

### How do I add Ruah to Claude Code?

Run this command in your terminal: claude mcp add ruah-mcp -- npx -y ruah-mcp

### What are the best alternatives to Ruah?

The closest alternatives to Ruah are HyperFrames by HeyGen, ffmpeg-skill, ASTra, AvatarSay — Fictional Character & Talking Video MCP and ChartAnt.

## Alternatives

- [HyperFrames by HeyGen](https://ai-powered.com/mcp/hyperframes-by-heygen): HyperFrames by HeyGen is a freemium MCP server for design and media.
- [ffmpeg-skill](https://ai-powered.com/mcp/ffmpeg-skill): ffmpeg-skill is an open-source MCP server for design and media.
- [ASTra](https://ai-powered.com/mcp/astra): ASTra is a freemium MCP server for files and documents.
- [AvatarSay — Fictional Character & Talking Video MCP](https://ai-powered.com/mcp/avatarsay-fictional-character-and-talking-video-mcp): AvatarSay — Fictional Character & Talking Video MCP is a freemium MCP server for design and media.
- [ChartAnt](https://ai-powered.com/mcp/chartant): ChartAnt is a freemium MCP server for design and media.
- [VfxSmith](https://ai-powered.com/mcp/vfxsmith): VfxSmith is a freemium MCP server for design and media.
- [CalderFlow](https://ai-powered.com/mcp/calderflow): CalderFlow is a free MCP server for design and media.
- [Hourlore](https://ai-powered.com/mcp/hourlore): Hourlore is a freemium MCP server for design and media.

---
Source: https://ai-powered.com/mcp/ruah
