How do I use remove-background?

1. Click on "Deploy 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.

remove-background

by adamryczkowski

Overview Schema Source Related Servers Discussions Admin

Python

Local

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

Related MCP server: Image Toolkit MCP Server

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

Available Tools

4 tools

get_model_cache_statusA

Get current status of the model cache.

Returns information about which models are currently loaded, auto-unload settings, and time until automatic unload.

Returns: Dictionary with cache status including loaded models and timeout info.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral burden. "Get current status" clearly signals a read-only operation, and the description states that it returns information rather than modifying cache state. It does not explicitly say "does not alter the cache," but the wording is sufficiently transparent for a zero-parameter status tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short and front-loaded with the core purpose, but it is redundant: the first paragraph already lists loaded models, auto-unload settings, and timeout info, and the "Returns:" block repeats almost the same content. It could be tightened to a single concise statement.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This is a simple zero-parameter status tool with an output schema available, so the description is largely complete for invoking it correctly. It would be stronger with a brief note about using it before unload_models, but that gap overlaps with usage guidelines and is not critical for execution.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parametersaine and schema coverage is trivially 100%, so there is no parameter meaning for the description to add. Baseline 4 applies because no parameter documentation is needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description uses a specific verb, "Get", and resource, "status of the model cache", and enumerates what it returns: loaded models, auto-unload settings, and timeout info. It is clearly distinguishable from destructive siblings like unload_models, though it does not explicitly name them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains what the tool returns but provides no guidance on when to call it versus alternatives such as unload_models or list_background_models. There is no explicit use case, no exclusions, and no mention of related tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_background_modelsA

List all available background removal models.

Returns a list of models that can be used for background removal, including their descriptions and recommended use cases.

Returns: Dictionary with models list and default model information.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.7/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It discloses that the tool returns a dictionary with a models list and default model information, which gives some insight into the output. However, it does not explicitly state that this is a read-only operation, nor does it mention any side effects or performance implications. For a listing tool, this is acceptable but not rich.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with three sentences. The first sentence states the core purpose, the second adds detail, and the third specifies the return type. It is front-loaded and contains no filler, though the final sentence about returns might be redundant given the output schema exists, but it does not hurt.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple with no parameters and an output schema. The description covers what the tool does (lists models) and what the output contains (models with descriptions, use cases, and default info). This is sufficient for an agent to know when to call it and what to expect. There is no obvious missing context for this basic listing operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the description does not need to explain any. Baseline for 0 parameters is 4, and the description appropriately focuses on the output rather than input. No parameter-related information is missing.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'List' and the resource 'all available background removal models', which is distinct from sibling tools like remove_background (which likely removes) and unload_models (which unloads). It also specifies that it returns descriptions and recommended use cases, making its purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It does not mention scenarios where this tool is appropriate or when to avoid it, nor does it reference sibling tools. The only implicit context is that it lists models, but no explicit routing or exclusions are given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

remove_backgroundD

ParametersJSON Schema

Name	Required	Default
`model`	No	u2net
`image_path`	Yes
`output_path`	No
`alpha_matting`	No
`try_floodfill_first`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

unload_modelsA

Unload all cached ML models to free memory.

Call this tool when you're done processing images to free up RAM. ML models can consume 100MB-400MB each. Models will be automatically reloaded on the next background removal request.

Returns: Dictionary with unload status, including list of unloaded models.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With zero annotations, the description carries the full disclosure burden and meets it well. It discloses scope ('all cached'), resource cost (100MB-400MB each), the non-destructive automatic reload behavior on the next background removal request, and the return shape. The auto-reload detail is exactly what an agent needs to assess the risk of calling this mutating utility.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A front-loaded single-sentence summary is followed by brief, purposeful context on when to call, memory cost, and auto-reload behavior. The Returns line is slightly redundant given that an output schema exists, but the overall structure is tight and every other sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Complete for a zero-parameter utility tool with an output schema. An agent knows what the tool does, when to invoke it, why it matters (RAM relief), what it returns, and that it is safe because models reload automatically. Nothing needed to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters and 100% schema coverage, and the rubric establishes a baseline of 4 for zero-param tools. There is nothing to document and no coverage gap to compensate for.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening line states a specific verb ('Unload'), a precise resource ('all cached ML models'), and the goal ('free memory'). The action is inherently distinguishable from siblings such as remove_background, list_background_models, and get_model_cache_status, all of which serve clearly different operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit timing guidance: 'Call this tool when you're done processing images to free up RAM.' It doesn't name sibling alternatives by name, but the trigger condition is unambiguous and clearly implies this is the cleanup counterpart to the image-processing flow, exceeding mere implied usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

4 tool updatesv0.1.0Sep 15, 2026
- First observedget_model_cache_status
- First observedlist_background_models
- First observedremove_background
- First observedunload_models

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.1/5.0

Scored 2026-09-15 09:50 across 4 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: performing the removal, listing available models, unloading models, and checking cache status. Even without a description for remove_background, its name is unambiguous. Tool names and descriptions do not overlap in a way that would cause misselection.

Naming Consistency5/5

All tool names follow the same imperative verb + object pattern in snake_case: remove, list, unload, get. The naming style is consistent and predictable across the set.

Tool Count5/5

Four tools is well-scoped for a focused background-removal server: one core operation, one model discovery tool, and two resource-management tools. Each tool earns its place without unnecessary bulk.

Completeness5/5

The tool surface covers the full expected lifecycle for this domain: removing backgrounds, listing available models, checking cache state, and freeing memory. There are no obvious missing operations; model reloading is handled automatically, so an explicit load tool is unnecessary.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

mcp COAuth
com.wix
A Model Context Protocol server for Wix AI tools
Developer Tools Content Management Systems App Automation
216
hithereiamaliff-mcp-nextcloudOAuth
ai.smithery
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Cloud Storage File Systems Workplace & Productivity
238
Studex MCP ServerOAuth
io.github.itshivams
Model Context Protocol server for Studex tools, notifications, and profile integrations
Developer Tools
1
Maskr.io MCP Server AOAuth
io.maskr.mcp
AI-powered image processing via GPU. Remove backgrounds and upscale images (2x/4x) directly from any MCP client. OAuth 2.1 authenticated, returns processed images inline with download links. Free credits on signup at maskr.io.
Image & Video Processing Multimedia Processing App Automation
62

Related MCP Servers

Ideogram MCP Server
Image & Video Processing App Automation
Sunwood-ai-labs
A
license
C
quality
C
maintenance
A Model Context Protocol server that provides image generation capabilities using the Ideogram API, allowing users to create images from text prompts with customizable parameters.
Updated a year ago (2025-05-18 12:03 UTC)
1
17 npm
5
MIT
Image Toolkit MCP Server
Image & Video Processing Multimedia Processing
Kira-Pgr
A
license
Not graded
quality
F
maintenance
A server that provides AI-powered image generation, modification, and processing capabilities through the Model Context Protocol, leveraging Google Gemini models and other image services.
Updated a year ago (2025-03-19 22:49 UTC)
18
MIT
MCP Boilerplate
RAG Systems Agent Orchestration Developer Tools
iamsrikanthnani
A
license
Not graded
quality
D
maintenance
A server that implements the Model Context Protocol, providing a standardized way to connect AI models to different data sources and tools.
Updated a year ago (2025-05-12 06:05 UTC)
6 npm
11
MIT
MCP Server - Images
rmrfslashbin
A
license
Not graded
quality
D
maintenance
A Model Context Protocol server that enables AI-powered image generation through Stability AI and Black Forest Labs APIs, allowing users to create images from detailed text prompts with customizable settings and comprehensive metadata tracking.
Updated a year ago (2025-07-19 13:21 UTC)
MIT