Rawtherapee Mcp Server

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 (MCP) server for AI-assisted RAW photo development via RawTherapee 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) | | 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 5.9+ with CLI component installed
• An MCP-compatible client (see table above)

Verify the RawTherapee CLI is reachable before proceeding:

Windows (PowerShell):

& "C:\Program Files\RawTherapee\5.12\rawtherapee-cli.exe" --version

macOS:

/Applications/RawTherapee.app/Contents/MacOS/rawtherapee-cli --version

Linux:

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\claudedesktopconfig.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/claudedesktopconfig.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/claudedesktopconfig.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):

python -m venv "$env:USERPROFILE\.rawtherapee-mcp-env"
& "$env:USERPROFILE\.rawtherapee-mcp-env\Scripts\pip.exe" install rawtherapee-mcp-server

macOS / Linux:

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\claudedesktopconfig.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/claudedesktopconfig.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/claudedesktopconfig.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:

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

macOS / Linux:

~/.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\claudedesktopconfig.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/claudedesktopconfig.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/claudedesktopconfig.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:

{
  "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

# 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:

{
  "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:

{
  "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:

{
  "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/CLIENTCOMPATIBILITY.md](docs/CLIENTCOMPATIBILITY.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):

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:

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:

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:

& "$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:

~/.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 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
• Source: lucamarien/rawtherapee-mcp-server
• License: MIT

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