How do I use remove-background?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@remove-background remove background from product_photo.jpg" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

MCP Remove Background Server

A Model Context Protocol (MCP) server for removing backgrounds from images using AI-powered segmentation models.

Features

Background Removal: Remove backgrounds from images using AI-powered segmentation
- Multiple model options optimized for different image types
- Outputs PNG with full alpha transparency
- Fast flood-fill algorithm for simple backgrounds (optional)
Model Catalog: Access comprehensive information about all available background removal models

Supported Models

Model	Size	Best For	Quality
`u2net`	176MB	General purpose (default)	Good
`u2netp`	4MB	Lightweight/mobile	Moderate
`silueta`	43MB	General, smaller footprint	Good
`isnet-general-use`	176MB	General, newer	Very Good
`isnet-anime`	176MB	Anime/illustrations	Excellent for art
`birefnet-general`	400MB	Best quality	Excellent
`birefnet-general-lite`	100MB	Balanced	Very Good
`sam`	400MB	Segment Anything	Excellent

Installation

Option 1: Install with pipx (Recommended for CLI usage)

# Install directly from the repository
pipx install git+https://github.com/your-username/MCP-remove-background.git

# Or install from local directory
cd MCP-remove-background
pipx install .

# Run the server
mcp-remove-background

Option 2: Install with Poetry (Recommended for development)

# Clone the repository
git clone <repository-url>
cd MCP-remove-background

# Install dependencies with Poetry
just setup

# Run the server
poetry run mcp-remove-background
# Or
poetry run python -m MCP_remove_background.server

Option 3: Install with pip

# Install from the repository
pip install git+https://github.com/your-username/MCP-remove-background.git

# Or install from local directory
pip install .

# Run the server
mcp-remove-background

Usage

Running the Server

# If installed with pipx or pip
mcp-remove-background

# If using Poetry (development)
poetry run mcp-remove-background

# Alternative: run as Python module
poetry run python -m MCP_remove_background.server

# With FastMCP CLI (more options)
poetry run fastmcp run MCP_remove_background/server.py --transport http --port 8000

CLI Options

When using the fastmcp run command, you have additional options:

Option	Description
`--transport`, `-t`	Transport protocol: `stdio` (default), `http`, `sse`, `streamable-http`
`--host`	Host to bind to (default: 127.0.0.1)
`--port`, `-p`	Port for HTTP/SSE transport (default: 8000)
`--log-level`, `-l`	Log level: DEBUG, INFO, WARNING, ERROR, CRITICAL
`--no-banner`	Don't show the server banner

MCP Client Configuration

To use this MCP server with an AI agent, add the following configuration to your MCP client.

Claude Desktop (pipx installation)

If you installed with pipx, add to your Claude Desktop configuration file (~/.config/claude/claude_desktop_config.json on Linux, ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "remove-background": {
      "command": "mcp-remove-background"
    }
  }
}

Claude Desktop (Poetry installation)

If you're using Poetry for development:

{
  "mcpServers": {
    "remove-background": {
      "command": "poetry",
      "args": ["run", "mcp-remove-background"],
      "cwd": "/path/to/MCP-remove-background"
    }
  }
}

Cline / Roo Code

Add to your VS Code settings or Cline MCP configuration:

{
  "mcpServers": {
    "remove-background": {
      "command": "mcp-remove-background"
    }
  }
}

Generic MCP Client (Copy-Paste Ready)

For pipx/pip installation:

{
  "remove-background": {
    "command": "mcp-remove-background"
  }
}

For Poetry installation:

{
  "remove-background": {
    "command": "poetry",
    "args": ["run", "mcp-remove-background"],
    "cwd": "/path/to/MCP-remove-background"
  }
}

Configuration Options:

Field	Description
`command`	The command to run (`poetry` for Poetry-managed projects)
`args`	Command arguments to start the MCP server
`cwd`	Working directory - set to your MCP-remove-background installation path

Important: Replace /path/to/MCP-remove-background with the actual path to your installation.

Tools

`remove_background`

Remove the background from an image, replacing it with transparency.

Parameters:

image_path (required): Path to the image file to process
output_path (optional): Path for the output PNG file (auto-generated if not specified)
model (optional): Background removal model (default: "u2net")
alpha_matting (optional): Enable alpha matting for smoother edges (default: false)
try_floodfill_first (optional): Try fast flood-fill before ML (default: true)

Returns:

success: Whether background removal succeeded
input_path: Path to the input file
output_path: Path to the output PNG file with transparency
file_size_bytes: Size of the output file in bytes
method_used: "floodfill" or model name
model_used: The model that was configured
error: Error message if removal failed

Example:

result = await remove_background(
    image_path="/path/to/image.png",
    model="isnet-anime"
)
if result["success"]:
    print(f"Transparent image saved to: {result['output_path']}")

`list_background_models`

List all available background removal models with their descriptions.

Parameters: None

Returns:

models: List of available models with id, name, description, and size
total_count: Number of available models
default_model: The default model used when not specified
usage_hint: How to use the model parameter

Example Response:

{
  "models": [
    {
      "id": "u2net",
      "name": "U2-Net",
      "description": "General purpose background removal model",
      "size": "176MB"
    },
    ...
  ],
  "total_count": 8,
  "default_model": "u2net",
  "usage_hint": "Pass model='model_id' to remove_background tool"
}

Development

Setup

# Initialize the development environment
just setup

Running Tests

# Run all tests with coverage
just test

# Run specific test file
poetry run pytest tests/unit/test_constants.py -v

Code Quality

# Run formatting
just format

# Run all pre-commit hooks (includes formatting, linting, type-checking)
just validate

# Run type checking only
just typecheck

Building

# Build wheel package
just package

# Test the built package
just test-package

# Clean build artifacts
just clean

Available Just Commands

Command	Description
`just setup`	Initialize development environment (Poetry deps + pre-commit hooks)
`just test`	Run unit tests with coverage report
`just typecheck`	Run static type checking with pyright
`just format`	Run formatting hooks (ruff, etc.)
`just validate`	Run all pre-commit hooks on all files
`just package`	Build wheel package into dist/
`just test-package`	Build, install, and smoke-test the package
`just clean`	Clean build artifacts and temporary files
`just recreate-venv`	Recreate virtual environment with specific Python version
`just serve-http`	Run MCP server with HTTP transport (shared mode)
`just mcp-status`	Check if MCP HTTP server is running

Project Structure

MCP-remove-background/
├── MCP_remove_background/
│   ├── __init__.py              # Package exports
│   ├── cli.py                   # CLI entry point
│   ├── config.py                # Configuration management
│   ├── constants.py             # Constants and type definitions
│   ├── exceptions.py            # Custom exceptions
│   ├── server.py                # FastMCP server definition
│   ├── services/
│   │   └── background_remover.py # Core background removal logic
│   ├── tools/
│   │   └── remove_background.py  # MCP tool definitions
│   └── utils/
│       └── file_utils.py         # File handling utilities
├── tests/
│   ├── conftest.py              # Pytest fixtures
│   ├── pytest.ini
│   ├── unit/
│   │   ├── test_constants.py
│   │   ├── test_exceptions.py
│   │   ├── test_background_remover.py
│   │   └── test_tools.py
│   ├── integration/
│   │   └── test_server.py
│   └── mocks/
│       └── rembg_mock.py
├── docs/
│   └── background-removal-mcp-plan.md
├── scripts/
│   ├── spack-ensure.sh
│   └── test-package.sh
├── pyproject.toml
├── justfile
├── README.md
└── spack.yaml

Spack Integration

This project uses Spack to manage system-level dependencies (like the Python interpreter). Spack is automatically installed to ~/.local/share/spack if not already available.

To manually activate the Spack environment:

source .spack-activate.sh

To update Spack packages:

spack -e . concretize --fresh-roots --force
spack -e . install

License

MIT License

remove-background