holocode-ai/rembg-mcp

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