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.

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)

Installation

From PyPI

pip install rawtherapee-mcp-server

From source

git clone https://github.com/lucamarien/rawtherapee-mcp-server
cd rawtherapee-mcp-server
pip install -e ".[dev]"

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.11\\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.

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

The package uses uvx which caches installed environments. To get updates:

Recommended: Pin to specific versions for stability:

"args": ["rawtherapee-mcp-server@1.0.3"]

Update the version number when you want to upgrade.

Alternative: Use @latest to attempt auto-updates (cache may interfere):

"args": ["rawtherapee-mcp-server@latest"]

Restart Claude Desktop to pick up new versions.

Force update:

uvx --force-reinstall rawtherapee-mcp-server

Check GitHub Releases for changelogs and upgrade notes.

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.11\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

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