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