📦

rawtherapee-mcp-server

MCP server for AI-assisted RAW photo development via RawTherapee

0 installs

Trust: 37 — Low

Content

Ask AI about rawtherapee-mcp-server

I know everything about rawtherapee-mcp-server. Ask me about installation, configuration, usage, or troubleshooting.

0/500

Loading tools...

Reviews

Documentation

RawTherapee MCP Server

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 for the full refresh procedure.

Windows (%APPDATA%\Claude\claude_desktop_config.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)

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

{
  "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\claude_desktop_config.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)

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

{
  "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\claude_desktop_config.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)

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

{
  "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/CLIENT_COMPATIBILITY.md.

Quick Start

After installation and client configuration, try this workflow:

"Analyze this photo" — analyze_image reads EXIF, computes histogram, generates a thumbnail, and returns processing recommendations
"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
"The shadows are too dark" — add_luminance_adjustment adds a shadow recovery spot, preview_with_adjustments shows the result
"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. If the version string is correct but new tools are missing, see docs/TROUBLESHOOTING.md.

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	Description
`add_luminance_adjustment`	Add luminance-based local adjustment (shadows/midtones/highlights/custom)
`list_local_adjustments`	List all Locallab spots in a profile
`adjust_local_spot`	Modify an existing Locallab spot
`remove_local_adjustment`	Remove a Locallab spot
`apply_local_preset`	Apply a predefined local adjustment preset with intensity scaling

Lens Correction (2)

Tool	Description
`apply_lens_correction`	Apply Lensfun auto-detect or Adobe LCP correction to a PP3 profile
`check_lens_support`	Query the Lensfun database for distortion/vignetting/TCA coverage

Film Simulation / LUT Support (4)

Tool	Description
`list_luts`	Scan `RT_HALDCLUT_DIR` for HaldCLUT film simulation LUTs, grouped by category
`apply_lut`	Write a HaldCLUT film simulation into a PP3 profile with configurable strength
`preview_lut`	Render an inline preview of a RAW file with a film simulation applied
`preview_lut_comparison`	Render 2–5 LUT previews side-by-side for quick comparison

Profile Inheritance (3)

Tool	Description
`create_profile_variant`	Derive a child PP3 from a parent template with section-level overrides
`list_profile_variants`	List all variants with override summaries, optionally filtered by parent
`update_base_profile`	Modify a base template and propagate changes to all child variants

Metadata Privacy (3)

Tool	Description
`inspect_metadata`	Classify JPEG/TIFF EXIF into sensitive/technical/rights buckets with privacy recommendations
`strip_metadata`	Losslessly remove GPS, serial numbers, software, and owner tags from a JPEG
`set_metadata`	Write copyright, artist, description, and keywords into a JPEG

Built-in Resources

PP3 Templates (5)

Template	Description
`neutral`	Minimal processing, camera white balance, basic sharpening
`warm_portrait`	Warm tones (5800K), gentle contrast, skin-friendly saturation
`moody_cinematic`	Cool tones (5200K), lifted blacks, reduced saturation, film look
`vivid_pet`	Warm tones (5600K), boosted saturation and vibrance, strong sharpening
`bw_classic`	Black & white via channel mixer, high contrast, strong sharpening

Device Presets (19)

Mobile (7): Samsung Galaxy S26 Ultra, Galaxy S25 Ultra, iPhone 16 Pro Max, iPhone 16, Google Pixel 9 Pro, generic 9:16, generic 9:19.5
Desktop (5): 4K UHD (3840x2160), WQHD (2560x1440), Full HD (1920x1080), Ultrawide 21:9 (3440x1440), Dual 4K 32:9 (7680x2160)
Photo Formats (7): 3:2 (35mm), 4:3, 16:9, 1:1 (square), 5:4, 4:5 (Instagram portrait), 2:3 (portrait 35mm)

Custom presets can be added via add_device_preset_tool and persist across sessions.

Local Adjustment Presets (7)

Preset	Description
`shadow_recovery`	Brighten shadows without affecting highlights
`highlight_protection`	Compress highlights to recover detail
`split_tone_warm_cool`	Warm shadows, cool highlights
`midtone_contrast`	Add contrast to midtones only
`shadow_desaturation`	Desaturate shadow areas for a clean look
`amoled_optimize`	High contrast and deep blacks for AMOLED displays
`hdr_natural`	Natural HDR look with lifted shadows and compressed highlights

Presets accept an intensity parameter (50 = default, 25 = half, 100 = double).

Environment Variables

Variable	Default	Description
`RT_CLI_PATH`	Auto-detect	Path to `rawtherapee-cli` binary
`RT_OUTPUT_DIR`	`~/Pictures/rawtherapee-mcp-output`	Default output directory
`RT_PREVIEW_DIR`	OS temp dir	Preview image directory
`RT_CUSTOM_TEMPLATES_DIR`	`./custom_templates`	Custom PP3 templates directory
`RT_PREVIEW_MAX_WIDTH`	`1200`	Max preview width in pixels
`RT_JPEG_QUALITY`	`95`	Default JPEG quality (1-100)
`RT_LOG_LEVEL`	`WARNING`	Logging level (DEBUG, INFO, WARNING, ERROR)

See .env.example for a documented configuration template.

Known Limitations

RawTherapee CLI must be installed separately — it is not a Python package and cannot be installed via pip
stdio transport only — designed for local desktop use, no HTTP/SSE server mode
RT 5.12 crop+resize bug — RawTherapee 5.12 silently ignores Crop when Resize is also enabled in the same PP3 profile; the server applies a crop-only workaround automatically
1MB MCP tool response limit — preview resolution is managed to stay within Claude Desktop's response size limit
No pixel-level editing — no retouching, object removal, frequency separation, or content-aware fill
No multi-image compositing — no HDR merge, panorama stitching, or focus stacking
Luminance masks are tonal only — no spatial or subject-aware masking
Integration tests require a RawTherapee installation and are skipped by default

Troubleshooting

RawTherapee not found:

Run check_rt_status to see detection details
Set RT_CLI_PATH to the full path of rawtherapee-cli:
- Windows: C:\Program Files\RawTherapee\5.12\rawtherapee-cli.exe
- macOS: /Applications/RawTherapee.app/Contents/MacOS/rawtherapee-cli
- Linux: /usr/bin/rawtherapee-cli

Paths with spaces on Windows:

Always use the full path in RT_CLI_PATH, including quotes if your shell requires them
Environment variables in MCP client config JSON do not need extra escaping

Preview images too large:

Reduce RT_PREVIEW_MAX_WIDTH (default: 1200)
Preview tools auto-thumbnail to stay within the 1MB response limit

Server not responding:

Verify the entry in your MCP client config is correct
Restart your MCP client after config changes
Set RT_LOG_LEVEL=DEBUG to see detailed logs on stderr

New version installed but old tools still showing in Claude: See docs/TROUBLESHOOTING.md - Stale tool list after update. Short version: fully quit Claude Desktop (it runs as a background process), then relaunch.

Docker

docker build -t rawtherapee-mcp-server .
docker run -i --rm \
  -v /path/to/photos:/photos \
  -v /path/to/output:/output \
  -e RT_OUTPUT_DIR=/output \
  rawtherapee-mcp-server

Development

See docs/DEVELOPMENT.md for full setup instructions.

git clone https://github.com/lucamarien/rawtherapee-mcp-server
cd rawtherapee-mcp-server
pip install -e ".[dev]"
make validate    # lint + format + typecheck + test + security + audit

Testing

# Unit tests (mocked, no RawTherapee required)
pytest -v

# Integration tests (requires RawTherapee installation)
pytest -m integration -v

MCP Inspector

npx @modelcontextprotocol/inspector uv run rawtherapee-mcp

Contributing

See CONTRIBUTING.md for development guidelines, coding standards, and PR checklist.

License

MIT

rawtherapee-mcp-server

Reviews

Documentation

RawTherapee MCP Server

MCP Client Compatibility

Prerequisites

Installation

Option A - uvx

Option B - pip + venv

1. Create the venv and install

2. Configure Claude Desktop

3. Verify the install

Client Configuration

Claude Desktop

Claude Code

Cursor

Windsurf

Cline (VS Code)

Quick Start

Updating

With uvx

With pip + venv

Verify the update worked

Available Tools (49)

Discovery & Configuration (5)

Metadata & Analysis (5)

Profile Management (8)

Preview & Visualization (7)

Processing & Export (4)

Crop & Device (3)

Local Adjustments (5)

Lens Correction (2)

Film Simulation / LUT Support (4)

Profile Inheritance (3)

Metadata Privacy (3)

Built-in Resources

PP3 Templates (5)

Device Presets (19)

Local Adjustment Presets (7)

Environment Variables

Known Limitations

Troubleshooting

Docker

Development

Testing

MCP Inspector

Contributing

License

Security Checklist