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

git clone <repository-url>
cd rembg-mcp
./setup.sh

Windows

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:

1. Create virtual environment:

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

2. Install dependencies:

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

3. Test installation:

python test_server.py
python validate_setup.py

4. Download AI models:

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

5. For GPU support:

pip install -e ".[gpu]"

🔧 MCP Configuration

Claude Desktop Setup

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

2. 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"
      }
    }
  }
}

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

4. Restart Claude Desktop

Testing Your Setup

After configuration, test your MCP server:

1. Start the server manually:

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

2. Verify MCP connection in Claude Desktop:

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

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

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

# 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

• Rembg Library Documentation
• MCP Protocol Specification
• Claude Code Documentation

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. 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