Rembg MCP Server

An MCP (Model Context Protocol) server for the rembg background removal library. Remove image backgrounds using AI models through Claude Code, Claude Desktop, Cursor, and other MCP-compatible tools.

🎯 Features

🖼️ Image Processing: Remove backgrounds from single images or batch process folders
🤖 Multiple AI Models: u2net, birefnet, isnet, sam, and more specialized models
⚡ Performance Optimized: Model session reuse for efficient batch processing
🎨 Advanced Options: Alpha matting, mask-only output, custom backgrounds
🌍 Cross-Platform: Support for Windows, macOS, and Linux
🔧 Easy Integration: Works with Claude Desktop, Claude Code CLI, Cursor IDE

📦 Quick Start

🚀 One-Click Installation

Linux/macOS ``bash git clone <repository-url> cd rembg-mcp ./setup.sh ``

Windows ``cmd git clone <repository-url> cd rembg-mcp setup.bat ``

The setup scripts will automatically:

Check Python 3.10+ requirement
Create virtual environment
Install all dependencies
Configure MCP server
Test the installation
Guide you through AI model downloads

🔧 Manual Installation

If you prefer manual installation or need custom configuration:

Create virtual environment:

python3 -m venv rembg
source rembg/bin/activate  # Linux/macOS
# or
rembg\Scripts\activate.bat  # Windows

Install dependencies:

pip install --upgrade pip
pip install mcp "rembg[cpu,cli]" pillow
pip install -e .

Test installation:

python test_server.py
python validate_setup.py

Download AI models:

./download_models.sh     # Linux/macOS
# or
python download_models.py  # Windows (from activated venv)

For GPU support:

pip install -e ".[gpu]"

🔧 MCP Configuration

Claude Desktop Setup

Find your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Add the rembg server configuration:

{
  "mcpServers": {
    "rembg": {
      "command": "/path/to/rembg-mcp/start_server.sh",
      "cwd": "/path/to/rembg-mcp",
      "env": {
        "REMBG_HOME": "~/.u2net",
        "OMP_NUM_THREADS": "4"
      }
    }
  }
}

Replace /path/to/rembg-mcp with your actual project path

Restart Claude Desktop

Testing Your Setup

After configuration, test your MCP server:

Start the server manually:

./start_server.sh  # Linux/macOS
# or
start_server.bat   # Windows

Verify MCP connection in Claude Desktop:

Look for the rembg tools in your Claude conversation
Try a simple command: "List available MCP tools"

Test with a sample image:

Ask Claude: "Use rembg-i to remove the background from test.jpg"
The server will process your request and return results

Claude Code CLI Setup

Add to your Claude Code settings:

{
  "mcpServers": {
    "rembg": {
      "command": "/path/to/rembg-mcp/start_server.sh",
      "cwd": "/path/to/rembg-mcp",
      "env": {
        "REMBG_HOME": "~/.u2net",
        "OMP_NUM_THREADS": "4"
      }
    }
  }
}

Cursor IDE Setup

Add to your Cursor settings or workspace .cursor/settings.json:

{
  "mcp.servers": {
    "rembg": {
      "command": "/path/to/rembg-mcp/start_server.sh",
      "args": [],
      "cwd": "/path/to/rembg-mcp"
    }
  }
}

Windows Configuration

For Windows users, use start_server.bat instead:

{
  "mcpServers": {
    "rembg": {
      "command": "C:\\path\\to\\rembg-mcp\\start_server.bat",
      "cwd": "C:\\path\\to\\rembg-mcp"
    }
  }
}

🚀 How to Use

Once configured, you can use the rembg tools directly in your MCP-compatible application:

Basic Usage Examples

Single Image Processing: `` Remove the background from my photo.jpg and save it as photo_nobg.png ``

Batch Processing: `` Process all images in my Photos folder and remove their backgrounds ``

Advanced Processing: `` Use the birefnet-portrait model to remove backgrounds from all portrait photos in my folder, apply alpha matting for better edges, and save them to a new folder ``

🛠️ Available MCP Tools

rembg-i - Single Image Background Removal

Removes background from a single image file with high precision.

Required Parameters:

input_path: Path to the source image file
output_path: Where to save the processed image

Optional Parameters:

model: AI model to use (default: "u2net")
alpha_matting: Improve edge quality (default: false)
only_mask: Output black/white mask only (default: false)

Supported formats: JPG, PNG, BMP, TIFF, WebP

rembg-p - Batch Folder Processing

Processes all images in a folder automatically.

Required Parameters:

input_folder: Source folder containing images
output_folder: Destination folder for processed images

Optional Parameters:

model: AI model to use (default: "u2net")
alpha_matting: Improve edge quality (default: false)
only_mask: Output masks only (default: false)
file_extensions: File types to process (default: common image formats)

Features:

Automatically finds all supported images
Preserves original filenames with .out.png suffix
Detailed progress reporting
Error handling for individual files

🤖 Supported AI Models

| Model | Use Case | Size | Quality | |-------|----------|------|---------| | u2net | General purpose (default) | Medium | Good | | u2netp | Lightweight version | Small | Good | | u2net_human_seg | Human subjects | Medium | Good | | u2net_cloth_seg | Clothing segmentation | Medium | Good | | silueta | Lightweight general | Small | Good | | isnet-general-use | High quality general | Large | Excellent | | isnet-anime | Anime characters | Large | Excellent | | birefnet-general | High accuracy general | Large | Excellent | | birefnet-portrait | Portrait photos | Large | Excellent | | birefnet-massive | Massive dataset trained | X-Large | Best | | sam | Segment Anything (prompt-based) | Large | Variable |

🎯 Model Recommendations

For beginners: Start with u2net (default) - good balance of speed and quality

For best quality: Use birefnet-general or birefnet-massive

For portraits: Use birefnet-portrait - specialized for human subjects

For anime/cartoons: Use isnet-anime - optimized for animated content

For speed: Use u2netp or silueta - faster processing for batch jobs

📥 Downloading Models

Models are downloaded automatically when first used, but you can pre-download them:

# Interactive selection (recommended)
./download_models.sh              # Linux/macOS

# Download specific models
./download_models.sh u2net birefnet-portrait

# Download all models
./download_models.sh all

# Windows (from activated virtual environment)
python download_models.py         # Interactive
python download_models.py u2net birefnet-portrait

Models are cached in ~/.u2net/ and only need to be downloaded once.

🔧 Configuration

Environment Variables

REMBG_HOME: Model storage directory (default: ~/.u2net)
OMP_NUM_THREADS: Number of CPU threads for processing (default: 4)
MODEL_CHECKSUM_DISABLED: Skip model checksum verification

Advanced Options

Alpha Matting: Improves edge quality but increases processing time
Mask Only: Returns black/white mask instead of transparent cutout
Custom Background Colors: Replace transparent areas with solid colors
Batch Processing: Automatically reuses model sessions for efficiency

📁 Project Structure

rembg-mcp/
├── rembg_mcp/
│   ├── __init__.py
│   └── server.py                      # Main MCP server implementation
├── rembg/                             # Virtual environment (git-ignored)
├── setup.sh                           # Linux/macOS setup script
├── setup.bat                          # Windows setup script
├── start_server.sh                    # Linux/macOS server startup
├── start_server.bat                   # Windows server startup (generated)
├── pyproject.toml                     # Python package configuration
├── claude_desktop_config.json         # Claude Desktop config (Linux/macOS)
├── claude_desktop_config_windows.json # Claude Desktop config (Windows)
├── test_server.py                     # Installation test
├── validate_setup.py                  # Comprehensive setup validation
├── download_models.py                 # AI model download utility (Python)
├── download_models.sh                 # AI model download script (Linux/macOS)
├── example_usage.py                   # Usage examples
├── README.md                          # This file
├── USAGE_CN.md                       # Chinese documentation
└── CLAUDE.md                         # Claude Code context file

🚨 Troubleshooting

Common Issues

MCP Server Not Found

Verify the command path in your MCP configuration
Ensure the script is executable: chmod +x start_server.sh
Check that the virtual environment exists: ls rembg/

Python Version Issues ```bash python --version # Must be 3.10+

If wrong version, install Python 3.10+ and recreate venv


**Model Download Problems**

Clear model cache and re-download

rm -rf ~/.u2net

Re-download models manually

./download_models.sh # Linux/macOS python download_models.py # Windows

Download a specific model

./download_models.sh u2net # Linux/macOS python download_models.py u2net # Windows ```

Memory or Performance Issues ```bash

Reduce CPU threads

export OMP_NUM_THREADS=2

Use lighter models (u2netp, silueta) instead of large ones


**Installation Problems**

Clean reinstall

rm -rf rembg/ ./setup.sh # Or setup.bat on Windows ```

Getting Help

Run python validate_setup.py for detailed diagnostics
Check server logs when starting manually
Ensure your MCP client supports the latest protocol version

📚 Additional Resources

🤝 Contributing

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

danielgatis/rembg - The excellent background removal library
Anthropic - For the MCP protocol and Claude
The open source community for the various AI models

rembg-mcp