explaingit

frozenpepper/fp-background_obliterator

★ 1PythonAudience · designerComplexity · 3/5ActiveLicenseSetup · moderate

TLDR

Local PyQt6 app and MCP server that removes image backgrounds with InSPyReNet, supports layers and masks, and exposes five tools to Claude Desktop, Cursor, and Windsurf. Runs fully on the user's machine.

Mindmap

mindmap
  root((bg-obliterator))
    Inputs
      JPG PNG WEBP images
      Threshold and blur settings
      MCP tool calls
    Outputs
      Transparent PNG
      Flat background JPG
      Layered composite
    Use Cases
      Local product photo cutout
      Composite with layer panel
      Agent driven image edits
      Privacy first batch removal
    Tech Stack
      Python
      PyQt6
      InSPyReNet
      OpenCV
      MCP
      CUDA
      MPS

Things people build with this

USE CASE 1

Run a local desktop app that removes photo backgrounds without sending images to a web service.

USE CASE 2

Composite layered images with opacity, ordering, and mask tuning sliders for product mockups.

USE CASE 3

Connect to Claude Desktop or Cursor so an agent can call remove_background and apply_mask on local files.

USE CASE 4

Batch process photos to transparent PNGs from a launcher script on macOS, Linux, or Windows.

Tech stack

PythonPyQt6InSPyReNetOpenCVMCPCUDA

Getting it running

Difficulty · moderate Time to first run · 30min

Launch scripts build a Python 3.10+ venv and download model weights on first run, which takes a few minutes.

MIT license, free to use, modify, and redistribute as long as the original copyright notice stays.

In plain English

FP-Background_Obliterator is a Python tool for removing the background from photos and compositing layered images, all running locally on the user's own computer. The author writes that no image data leaves the machine, which is the main selling point compared to web services. The background cutout itself is done by a neural network called InSPyReNet, and the rest of the image handling uses OpenCV. The project can be used in two ways. The first is an interactive desktop application built with PyQt6. It has a layer panel similar to image editing apps, with reordering, grouping into folders, per-layer opacity, and visibility toggles. It supports rectangular selections, copy and paste with the system clipboard, and three sliders for tuning the cutout edge: a threshold from 0 to 255, an erode or dilate shift between minus 20 and plus 20 pixels, and a blur radius from 0 to 20 for softer borders. It reads JPG, PNG, and WEBP, and exports either a transparent PNG or a flat-background JPG. The second way to use it is as a Model Context Protocol server. MCP is a standard for letting AI assistants call external tools, and the README gives copy-paste configurations for Claude Desktop, the Cursor IDE, and the Windsurf IDE. Once connected, the agent gets five tools it can call: remove_background, get_mask, apply_mask, edit_image for things like brightness and cropping, and a composite layers tool for combining images. Each tool documents its arguments, including the same threshold, shift, and blur controls available in the GUI. Launching is handled by scripts that build a local Python virtual environment and install dependencies. macOS and Linux users run launch_headless.sh or launch_ui.sh, and Windows users run the equivalent .bat files. On Apple Silicon the tool uses Metal Performance Shaders, on NVIDIA hardware it uses CUDA, and otherwise it falls back to CPU. Python 3.10 or newer is required. The repository has 1 star and is MIT licensed.

Copy-paste prompts

Prompt 1
Run launch_ui.sh from FP-Background_Obliterator on macOS Apple Silicon, confirm it uses MPS, and remove the background from a folder of product photos.
Prompt 2
Wire FP-Background_Obliterator into Claude Desktop as an MCP server and call remove_background then apply_mask on a test image.
Prompt 3
Write a Python script that drives FP-Background_Obliterator headless to batch convert all JPGs in a folder to transparent PNGs with threshold 200 and blur 3.
Prompt 4
Add a new MCP tool to FP-Background_Obliterator that crops to the alpha bounding box after remove_background completes.
Prompt 5
Debug why FP-Background_Obliterator falls back to CPU on my NVIDIA GPU and force it to use CUDA in the launch script.
Open on GitHub → Explain another repo

Generated 2026-05-22 · Model: sonnet-4-6 · Verify against the repo before relying on details.