Rawtherapee Server

CI PyPI Python License: MIT

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.

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:

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.

{
  "mcpServers": {
    "rawtherapee": {
      "command": "uvx",
      "args": ["[email protected]"],
      "env": {
        "RT_CLI_PATH": "C:\\Program Files\\RawTherapee\\5.12\\rawtherapee-cli.exe",
        "RT_OUTPUT_DIR": "C:\\Users\\YourName\\Pictures\\rawtherapee-output"
      }
    }
  }
}

{
  "mcpServers": {
    "rawtherapee": {
      "command": "uvx",
      "args": ["[email protected]"],
      "env": {
        "RT_OUTPUT_DIR": "/Users/yourname/Pictures/rawtherapee-output"
      }
    }
  }
}

{
  "mcpServers": {
    "rawtherapee": {
      "command": "uvx",
      "args": ["[email protected]"],
      "env": {
        "RT_OUTPUT_DIR": "/home/yourname/Pictures/rawtherapee-output"
      }
    }
  }
}

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.

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

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

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

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

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

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

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

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. 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)

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)

• 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)

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

Environment Variables

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