# Rawtherapee Mcp Server

> MCP server that lets AI edit RAW photos through RawTherapee CLI. With inline image previews - the LLM can see, analyze, and iteratively refine photos like a human editor.

- **Type:** MCP server
- **Install:** `agentstack add mcp-lucamarien-rawtherapee-mcp-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [lucamarien](https://agentstack.voostack.com/s/lucamarien)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [lucamarien](https://github.com/lucamarien)
- **Source:** https://github.com/lucamarien/rawtherapee-mcp-server

## Install

```sh
agentstack add mcp-lucamarien-rawtherapee-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# RawTherapee MCP Server

[](https://github.com/lucamarien/rawtherapee-mcp-server/actions/workflows/ci.yml)
[](https://pypi.org/project/rawtherapee-mcp-server/)
[](https://pypi.org/project/rawtherapee-mcp-server/)
[](LICENSE)

Cross-platform [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server for AI-assisted RAW photo development via [RawTherapee](https://rawtherapee.com/) CLI. Provides **49 tools** for profile generation, image processing, visual previews, batch operations, device presets, luminance-based local adjustments, lens correction, film simulation LUTs, profile inheritance, and metadata privacy.

**What makes it unique:** The LLM can *see* the photos it's editing. Preview tools return inline Base64 images via MCP's ImageContent protocol, creating a visual feedback loop where the AI analyzes the image, adjusts settings, previews the result, and iterates — just like a human editor.

## MCP Client Compatibility

Not all MCP clients handle inline images the same way. The visual feedback loop requires a client that renders `ImageContent` from tool responses and a backing LLM with vision capabilities.

| Client | MCP Support | Image Display | Visual Workflow | Status |
|--------|------------|---------------|----------------|--------|
| **Claude Desktop** | Full | Yes | Full | Tested |
| **Claude Code** | Full | No (terminal) | Partial | Tested — images not rendered in terminal, but processing and text analysis work fully |
| **Cursor** | Full | Should work | Should work | Untested — MCP docs indicate ImageContent support |
| **Windsurf** | Full | Should work | Should work | Untested |
| **Cline** | Partial | Unknown | Unknown | Untested — community reports suggest ImageContent may not render ([#1865](https://github.com/cline/cline/issues/1865)) |
| **Zed** | Full | Unknown | Unknown | Untested |

**Minimum requirements for the full visual workflow:**
- MCP client renders `ImageContent` (type: "image", data: base64, mimeType: "image/jpeg") from tool responses
- Backing LLM supports vision/image analysis (e.g. Claude with vision)
- Tool response size accommodates ~150KB previews (most clients: 1MB limit)

**Text-only clients:** All 49 tools work without inline images. Preview tools return file paths instead. The LLM can still read EXIF metadata, histogram statistics, generate profiles, batch process, and use luminance presets — the visual feedback loop is the only feature that requires image support.

## Prerequisites

- Python 3.11+
- [RawTherapee](https://rawtherapee.com/) 5.9+ with CLI component installed
- An MCP-compatible client (see table above)

Verify the RawTherapee CLI is reachable before proceeding:

**Windows (PowerShell):**
```powershell
& "C:\Program Files\RawTherapee\5.12\rawtherapee-cli.exe" --version
```

**macOS:**
```bash
/Applications/RawTherapee.app/Contents/MacOS/rawtherapee-cli --version
```

**Linux:**
```bash
rawtherapee-cli --version
```

## Installation

Two supported methods - pick the one that matches your priorities:

| Method | Choose when you want |
|--------|---------------------|
| **uvx** | Minimal setup, no persistent install, standard MCP community pattern |
| **pip + venv** | Explicit version control, predictable updates, easier debugging, air-gapped environments |

### Option A - uvx

No persistent install. uvx downloads, caches, and runs the server on demand.

**Important:** always pin a specific version. The unpinned form (`"rawtherapee-mcp-server"`) locks to the first resolved version and will not auto-upgrade on its own. See [Updating](#updating) for the full refresh procedure.

Windows (%APPDATA%\Claude\claude_desktop_config.json)

```json
{
  "mcpServers": {
    "rawtherapee": {
      "command": "uvx",
      "args": ["rawtherapee-mcp-server@1.0.4"],
      "env": {
        "RT_CLI_PATH": "C:\\Program Files\\RawTherapee\\5.12\\rawtherapee-cli.exe",
        "RT_OUTPUT_DIR": "C:\\Users\\YourName\\Pictures\\rawtherapee-output"
      }
    }
  }
}
```

macOS (~/Library/Application Support/Claude/claude_desktop_config.json)

```json
{
  "mcpServers": {
    "rawtherapee": {
      "command": "uvx",
      "args": ["rawtherapee-mcp-server@1.0.4"],
      "env": {
        "RT_OUTPUT_DIR": "/Users/yourname/Pictures/rawtherapee-output"
      }
    }
  }
}
```

RT CLI is auto-detected at `/Applications/RawTherapee.app/Contents/MacOS/rawtherapee-cli`. Set `RT_CLI_PATH` if your installation differs.

Linux (~/.config/Claude/claude_desktop_config.json)

```json
{
  "mcpServers": {
    "rawtherapee": {
      "command": "uvx",
      "args": ["rawtherapee-mcp-server@1.0.4"],
      "env": {
        "RT_OUTPUT_DIR": "/home/yourname/Pictures/rawtherapee-output"
      }
    }
  }
}
```

RT CLI is auto-detected at `/usr/bin/rawtherapee-cli`. Set `RT_CLI_PATH` if needed.

### Option B - pip + venv

Explicit install with a dedicated virtual environment. You control exactly which version is running and updates are transparent.

#### 1. Create the venv and install

**Windows (PowerShell):**
```powershell
python -m venv "$env:USERPROFILE\.rawtherapee-mcp-env"
& "$env:USERPROFILE\.rawtherapee-mcp-env\Scripts\pip.exe" install rawtherapee-mcp-server
```

**macOS / Linux:**
```bash
python3 -m venv ~/.rawtherapee-mcp-env
~/.rawtherapee-mcp-env/bin/pip install rawtherapee-mcp-server
```

#### 2. Configure Claude Desktop

Point Claude Desktop at the venv's entry-point script directly. No activation step is needed - the path is absolute.

Windows (%APPDATA%\Claude\claude_desktop_config.json)

```json
{
  "mcpServers": {
    "rawtherapee": {
      "command": "C:\\Users\\YourName\\.rawtherapee-mcp-env\\Scripts\\rawtherapee-mcp-server.exe",
      "args": [],
      "env": {
        "RT_CLI_PATH": "C:\\Program Files\\RawTherapee\\5.12\\rawtherapee-cli.exe",
        "RT_OUTPUT_DIR": "C:\\Users\\YourName\\Pictures\\rawtherapee-output"
      }
    }
  }
}
```

Replace `YourName` with your actual Windows username.

macOS (~/Library/Application Support/Claude/claude_desktop_config.json)

```json
{
  "mcpServers": {
    "rawtherapee": {
      "command": "/Users/yourname/.rawtherapee-mcp-env/bin/rawtherapee-mcp-server",
      "args": [],
      "env": {
        "RT_OUTPUT_DIR": "/Users/yourname/Pictures/rawtherapee-output"
      }
    }
  }
}
```

Linux (~/.config/Claude/claude_desktop_config.json)

```json
{
  "mcpServers": {
    "rawtherapee": {
      "command": "/home/yourname/.rawtherapee-mcp-env/bin/rawtherapee-mcp-server",
      "args": [],
      "env": {
        "RT_OUTPUT_DIR": "/home/yourname/Pictures/rawtherapee-output"
      }
    }
  }
}
```

#### 3. Verify the install

**Windows:**
```powershell
& "$env:USERPROFILE\.rawtherapee-mcp-env\Scripts\python.exe" -c "import rawtherapee_mcp; print(rawtherapee_mcp.__version__)"
```

**macOS / Linux:**
```bash
~/.rawtherapee-mcp-env/bin/python -c "import rawtherapee_mcp; print(rawtherapee_mcp.__version__)"
```

Expected output: the installed version number (e.g. `1.0.4`).

After editing `claude_desktop_config.json`, fully quit and restart Claude Desktop - closing the window alone leaves a background process running on both macOS and Windows.

## Client Configuration

### Claude Desktop

The RawTherapee CLI path is auto-detected on most systems. Set `RT_CLI_PATH` if auto-detection fails or RawTherapee is in a non-standard location.

Windows (%APPDATA%\Claude\claude_desktop_config.json)

```json
{
  "mcpServers": {
    "rawtherapee": {
      "command": "uvx",
      "args": ["rawtherapee-mcp-server"],
      "env": {
        "RT_CLI_PATH": "C:\\Program Files\\RawTherapee\\5.12\\rawtherapee-cli.exe",
        "RT_OUTPUT_DIR": "D:\\Photos\\Processed"
      }
    }
  }
}
```

macOS (~/Library/Application Support/Claude/claude_desktop_config.json)

```json
{
  "mcpServers": {
    "rawtherapee": {
      "command": "uvx",
      "args": ["rawtherapee-mcp-server"],
      "env": {
        "RT_OUTPUT_DIR": "/Users/you/Pictures/Processed"
      }
    }
  }
}
```

RT CLI is auto-detected at `/Applications/RawTherapee.app/Contents/MacOS/rawtherapee-cli`.

Linux (~/.config/Claude/claude_desktop_config.json)

```json
{
  "mcpServers": {
    "rawtherapee": {
      "command": "uvx",
      "args": ["rawtherapee-mcp-server"],
      "env": {
        "RT_OUTPUT_DIR": "/home/you/Pictures/Processed"
      }
    }
  }
}
```

RT CLI is auto-detected at `/usr/bin/rawtherapee-cli`, `/usr/local/bin/rawtherapee-cli`, or `/snap/bin/rawtherapee-cli`.

Development (from source)

Use `uv` to run from the cloned repository:

```json
{
  "mcpServers": {
    "rawtherapee": {
      "command": "uv",
      "args": ["--directory", "/path/to/rawtherapee-mcp-server", "run", "rawtherapee-mcp-server"],
      "env": {
        "RT_OUTPUT_DIR": "/home/you/Pictures/Processed"
      }
    }
  }
}
```

### Claude Code

```bash
# Published package
claude mcp add rawtherapee -- uvx rawtherapee-mcp-server

# Development (from source)
claude mcp add rawtherapee -- uv --directory /path/to/rawtherapee-mcp-server run rawtherapee-mcp
```

### Cursor

Add to `.cursor/mcp.json` in your project:

```json
{
  "mcpServers": {
    "rawtherapee": {
      "command": "uvx",
      "args": ["rawtherapee-mcp-server"],
      "env": {
        "RT_CLI_PATH": "/usr/bin/rawtherapee-cli",
        "RT_OUTPUT_DIR": "/home/you/Pictures/Processed"
      }
    }
  }
}
```

### Windsurf

Add to your Windsurf MCP configuration:

```json
{
  "mcpServers": {
    "rawtherapee": {
      "command": "uvx",
      "args": ["rawtherapee-mcp-server"],
      "env": {
        "RT_CLI_PATH": "/usr/bin/rawtherapee-cli",
        "RT_OUTPUT_DIR": "/home/you/Pictures/Processed"
      }
    }
  }
}
```

### Cline (VS Code)

Add to your Cline MCP settings:

```json
{
  "mcpServers": {
    "rawtherapee": {
      "command": "uvx",
      "args": ["rawtherapee-mcp-server"],
      "env": {
        "RT_CLI_PATH": "/usr/bin/rawtherapee-cli",
        "RT_OUTPUT_DIR": "/home/you/Pictures/Processed"
      }
    }
  }
}
```

> **Note:** Cline may not render inline images from tool responses. All text-based tools work normally.

For pip + venv config examples for all clients, see [docs/CLIENT_COMPATIBILITY.md](docs/CLIENT_COMPATIBILITY.md).

## Quick Start

After installation and client configuration, try this workflow:

1. **"Analyze this photo"** — `analyze_image` reads EXIF, computes histogram, generates a thumbnail, and returns processing recommendations
2. **"Make it warmer with more contrast"** — `generate_pp3_profile` creates a profile with warm white balance and contrast boost, `preview_before_after` shows the difference
3. **"The shadows are too dark"** — `add_luminance_adjustment` adds a shadow recovery spot, `preview_with_adjustments` shows the result
4. **"Export for my phone"** — `process_raw` with `device_preset` crops and processes at the right aspect ratio

## Updating

Both installation methods require a two-step procedure. Upgrading the package alone is not enough - Claude Desktop caches the MCP server's tool list. Always follow the full sequence: update package → fully quit Claude Desktop → relaunch.

### With uvx

uvx creates a per-package receipt that locks the resolved version. `--refresh` re-downloads the same locked version; it does not upgrade. To get a new release, clear the receipt and update the version pin:

**Windows (PowerShell):**

```powershell
uv cache clean rawtherapee-mcp-server
# Update the version pin in %APPDATA%\Claude\claude_desktop_config.json
# e.g. change @1.0.4 to @1.0.5
Get-Process *claude* -ErrorAction SilentlyContinue | Stop-Process -Force
Start-Process "$env:LOCALAPPDATA\AnthropicClaude\Claude.exe"
```

**macOS:**

```bash
uv cache clean rawtherapee-mcp-server
# Update the version pin in ~/Library/Application Support/Claude/claude_desktop_config.json
osascript -e 'quit app "Claude"' && sleep 2 && open -a Claude
```

**Linux:**

```bash
uv cache clean rawtherapee-mcp-server
# Update the version pin in ~/.config/Claude/claude_desktop_config.json
pkill -f claude && sleep 2 && claude &
```

### With pip + venv

**Windows:**

```powershell
& "$env:USERPROFILE\.rawtherapee-mcp-env\Scripts\pip.exe" install --upgrade rawtherapee-mcp-server
Get-Process *claude* -ErrorAction SilentlyContinue | Stop-Process -Force
Start-Process "$env:LOCALAPPDATA\AnthropicClaude\Claude.exe"
```

**macOS / Linux:**

```bash
~/.rawtherapee-mcp-env/bin/pip install --upgrade rawtherapee-mcp-server
# macOS:
osascript -e 'quit app "Claude"' && sleep 2 && open -a Claude
# Linux:
pkill -f claude && sleep 2 && claude &
```

### Verify the update worked

After relaunch, ask Claude:

> "What is the current rawtherapee-mcp-server version and how many tools are registered?"

Compare against [CHANGELOG.md](CHANGELOG.md). If the version string is correct but new tools are missing, see [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md#stale-tool-list-after-update).

Check [GitHub Releases](https://github.com/lucamarien/rawtherapee-mcp-server/releases) for full changelogs.

## Available Tools (49)

### Discovery & Configuration (5)

| Tool | Description |
|------|-------------|
| `check_rt_status` | Check RawTherapee installation, version, CLI path, and server configuration |
| `list_templates` | List all available PP3 templates (built-in and custom) |
| `list_device_presets` | List all device/format crop and resize presets |
| `list_raw_files` | Scan a directory for supported RAW files |
| `list_output_files` | List processed output files in the output directory |

### Metadata & Analysis (5)

| Tool | Description |
|------|-------------|
| `read_exif` | Read EXIF metadata with structured processing recommendations |
| `analyze_image` | All-in-one analysis: EXIF + histogram + thumbnail + recommendations |
| `batch_analyze` | Analyze multiple images with EXIF, recommendations, and thumbnails |
| `get_image_info` | Get dimensions, format, file size with optional inline thumbnail |
| `get_histogram` | RGB histogram with per-channel statistics, clipping, and SVG visualization |

### Profile Management (8)

| Tool | Description |
|------|-------------|
| `generate_pp3_profile` | Create a PP3 profile from base template + parameters + device preset |
| `read_profile` | Display PP3 profile contents in human-readable format |
| `adjust_profile` | Modify specific parameters in an existing profile |
| `compare_profiles` | Diff two profiles with optional visual A/B comparison |
| `save_template` | Save a profile as a reusable custom template |
| `create_template_from_description` | Create a template stub from natural language description |
| `delete_template` | Delete a custom template |
| `interpolate_profiles` | Blend two profiles by linear interpolation |

### Preview & Visualization (7)

| Tool | Description |
|------|-------------|
| `preview_raw` | Quick preview JPEG with optional inline image return |
| `preview_before_after` | Side-by-side neutral vs. profile comparison |
| `preview_exposure_bracket` | Multiple EV stops rendered for exposure comparison |
| `preview_white_balance` | Multiple WB presets with Kelvin values |
| `batch_preview` | Thumbnails for multiple RAW files |
| `preview_luminance_mask` | Grayscale mask showing local adjustment coverage |
| `preview_with_adjustments` | Preview with all Locallab spots active |

### Processing & Export (4)

| Tool | Description |
|------|-------------|
| `process_raw` | Process a RAW file to JPEG/TIFF/PNG with inline thumbnail |
| `apply_template` | Apply a template to process a RAW file with optional device preset |
| `batch_process` | Process multiple RAW files with the same profile |
| `export_multi_device` | Export one RAW optimized for multiple devices in one call |

### Crop & Device (3)

| Tool | Description |
|------|-------------|
| `adjust_crop_position` | Reposition crop (left/center/right, top/center/bottom, or pixel offsets) |
| `add_device_preset_tool` | Create a custom device preset |
| `delete_device_preset` | Delete a custom device preset |

### Local Adjustments (5)

| Tool

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [lucamarien](https://github.com/lucamarien)
- **Source:** [lucamarien/rawtherapee-mcp-server](https://github.com/lucamarien/rawtherapee-mcp-server)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-lucamarien-rawtherapee-mcp-server
- Seller: https://agentstack.voostack.com/s/lucamarien
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.