Transparent Background MCP

🎨 透明后台MCP服务器

  

🔒 隐私第一： 所有AI处理都在您的机器上本地进行。您的图像永远不会离开您的设备。

一个强大的模型上下文协议（MCP）服务器，使用最先进的人工智能模型从图像中删除背景。非常适合从任何图像创建透明PNG，支持多种尖端型号，包括BEN2、YOLO11和InSPyReNet。

✨ 特性

• 🤖 精心策划的人工智能模型：BEN2（最先进）、InSPyReNet（肖像）、YOLO11-S/L（速度）
• 🔒 100%本地处理：您的图像永远不会离开您的机器
• 📁 智能输入处理：自动接受文件路径和base64数据
• ⚡ GPU加速：自动GPU检测，CPU回退
• 📦 自动模型下载：无需手动设置
• 🎯 对象特定删除：使用YOLO11瞄准特定对象
• ⚡ 批处理：高效处理多张图像
• 🔧 硬件优化：根据您的系统自动推荐模型

🖼️ 视觉效果比较

使用真实的测试图像查看我们策划的模型之间的差异：

原始图像

模型结果

💡 小贴士：所有模型都支持文件路径和base64输入。BEN2默认用于获得最高质量的结果。

🚀 快速开始

先决条件

• Python 3.10+
• 紫外线 （推荐）或pip
• 4GB+RAM（建议8GB+）
• 可选：配备4GB+VRAM的NVIDIA GPU，可实现更快的处理速度

安装

紫外线（推荐）：

uv pip install "transparent-background-mcp @ git+https://github.com/joeleaver/transparent-background-mcp.git"

使用pip：

pip install "transparent-background-mcp @ git+https://github.com/joeleaver/transparent-background-mcp.git"

注： pip install torch 在某些平台上默认为仅CPU。有关GPU支持，请参阅 PyTorch安装页面 并首先安装相应的CUDA版本。

这将安装MCP服务器和所有必需的依赖项（PyTorch、Ultralytics、BEN2等）。模型权重在首次使用时自动下载。

运行服务器

transparent-background-mcp-server

或者直接运行而不安装（仅限紫外线）：

uvx --from "git+https://github.com/joeleaver/transparent-background-mcp.git" transparent-background-mcp-server

🔧 IDE集成

克劳德桌面

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json 窗户： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "transparent-background-mcp": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/joeleaver/transparent-background-mcp.git", "transparent-background-mcp-server"],
      "env": {
        "MODEL_CACHE_DIR": "~/.cache/transparent-background-mcp",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

VSCode与GitHub Copilot

添加到您的工作区 .vscode/mcp.json:

{
  "servers": {
    "transparent-background-mcp": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/joeleaver/transparent-background-mcp.git", "transparent-background-mcp-server"],
      "env": {
        "MODEL_CACHE_DIR": "~/.cache/transparent-background-mcp"
      }
    }
  }
}

光标

在光标设置中→ MCP服务器：

{
  "mcpServers": {
    "transparent-background-mcp": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/joeleaver/transparent-background-mcp.git", "transparent-background-mcp-server"],
      "env": {
        "MODEL_CACHE_DIR": "~/.cache/transparent-background-mcp"
      }
    }
  }
}

其他MCP客户端

对于任何兼容MCP的客户端，请使用以下标准配置：

{
  "servers": {
    "transparent-background-mcp": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/joeleaver/transparent-background-mcp.git", "transparent-background-mcp-server"],
      "env": {
        "MODEL_CACHE_DIR": "~/.cache/transparent-background-mcp"
      }
    }
  }
}

注： 配置文件位置因客户端而异。查看客户的文档以了解特定的配置文件路径。

🛠️ 可用工具

remove_background

使用AI模型从单个图像中删除背景。

参数：

• image_data （必填）：图像文件路径或base64编码的图像数据
• model_name （可选）：要使用的型号(ben2-base, inspyrenet-base, yolo11s-seg, yolo11l-seg)
• output_format （可选）：输出格式(PNG, JPEG)
• confidence_threshold （可选）：检测置信阈值（0.0-1.0）

注：当 image_data 是一个文件路径，默认情况下，输出图像也保存在输入文件旁边，使用带有后缀和适当扩展名的相同文件名。

• 默认后缀： -no-bg （可通过以下方式更改 OUTPUT_SUFFIX 任何人）
• 例子： photo.jpg -> photo-no-bg.png
• 对于喜欢内联内容的客户端，响应仍然包含base64数据。

batch_remove_background

高效地处理多幅图像。

参数：

• images_data （必填）：图像文件路径数组或base64图像数据
• model_name （可选）：要使用的型号
• output_format （可选）：输出格式
• confidence_threshold （可选）：检测置信阈值

注意：对于任何作为文件路径的条目，输出将使用与上述相同的默认后缀行为与每个输入文件一起保存（例如。， image.jpg -> image-no-bg.png).响应还包括base64编码的输出。

yolo_segment_objects

使用YOLO11模型分割特定对象。

参数：

• image_data （必填）：Base64编码图像数据
• model_name （可选）：YOLO型号变体(yolo11s-seg 或 yolo11l-seg)
• target_classes （可选）：要分割的特定对象类（例如。， ["person", "car"])
• confidence_threshold （可选）：检测置信阈值
• combine_masks （可选）：是否组合多个对象掩码

get_available_models

获取有关可用型号和系统建议的信息。

get_system_info

获取系统硬件信息和功能。

🤖 可用模型

📋 硬件要求

最低要求

• 中央处理器：任何现代处理器
• 随机存取存储器：4GB系统内存
• 图形处理器：无（支持CPU处理）
• 存储：型号为1GB

推荐设置

• 中央处理器：多核处理器
• 随机存取存储器：8GB+系统内存
• 图形处理器：4GB+VRAM（建议使用NVIDIA）
• 存储：2GB适用于多种型号

最佳表现

• 中央处理器：高性能多核
• 随机存取存储器：16GB+系统内存
• 图形处理器：8GB+显存（RTX 3070+、RTX 4060 Ti+）
• 存储：具有5GB+可用空间的SSD

🎯 模型性能比较

所有型号均已在仅CPU系统上使用1024x1024测试映像进行了测试。以下是性能结果：

⚡ 性能指标

🏆 模型建议

• 🥇 默认和最佳质量: ben2-base -最先进的结果（默认模型）
• 🎨 肖像画: inspyrenet-base -非常适合人物和细节主题
• 🚀 对于速度: yolo11s-seg -亚秒级处理
• ⚖️ 为了平衡: yolo11l-seg -1秒内质量好

📊 关键见解

• BEN2 是提供最高质量结果的默认模型
• InSPyReNet 擅长肖像和人物摄影
• YOLO11型号 当您需要快速处理时，提供最佳速度
• 所有型号均支持 文件路径 和 base64图像数据 作为输入
• GPU加速显著提高了所有型号的处理时间

💡 使用示例

基本背景移除

使用文件路径（推荐）：

# Simply provide the file path - BEN2 is used by default for best quality
"Remove the background from C:/Users/me/photos/portrait.jpg"

使用Base64（也支持）：

# The MCP server also accepts base64 encoded images
"Remove the background from this base64 image data"
# BEN2 model used by default for highest quality

速度与质量示例

对于速度（\<1秒）：

"Remove background from /path/to/image.jpg using yolo11s-seg for fastest processing"

对于质量（默认值-最佳结果）：

"Remove background from /path/to/portrait.jpg"
# Uses BEN2 by default for highest quality

对象特定删除

# Target specific objects with YOLO models
"Use yolo11l-seg to remove only the person from /path/to/photo.jpg, keeping the background"
# The system will automatically segment and remove only people

批处理

# Process multiple images efficiently
"Remove backgrounds from these product photos using yolo11s-seg"
# Provide multiple file paths: ["/path/to/photo1.jpg", "/path/to/photo2.jpg"]

🔧 配置

环境变量

创建一个 .env 文件或设置环境变量：

# Model cache directory
MODEL_CACHE_DIR=~/.cache/transparent-background-mcp

# Force CPU usage (disable GPU)
FORCE_CPU=false

# Default model
DEFAULT_MODEL=ben2-base

# Logging level
LOG_LEVEL=INFO

# Maximum batch size
MAX_BATCH_SIZE=4

# Clear GPU cache after operations
CLEAR_GPU_CACHE=true

高级配置

对于高级用户，您可以自定义模型行为：

{
  "mcpServers": {
    "transparent-background-mcp": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/joeleaver/transparent-background-mcp.git", "transparent-background-mcp-server"],
      "env": {
        "MODEL_CACHE_DIR": "/custom/cache/path",
        "DEFAULT_MODEL": "ben2-base",
        "MAX_BATCH_SIZE": "8",
        "LOG_LEVEL": "DEBUG",
        "FORCE_CPU": "false",
        "CLEAR_GPU_CACHE": "true"
      }
    }
  }
}

🐛 故障排除

常见问题

“找不到模型”或下载错误

• 解决方案：检查互联网连接并确保有足够的磁盘空间
• 替代：尝试其他型号或使用清除缓存 get_system_info 工具

GPU内存不足错误

• 解决方案：使用较小的模型（例如。， yolo11s-seg 而不是 yolo11l-seg)
• 替代：设置 FORCE_CPU=true 使用CPU处理

CPU处理速度慢

• 预期：CPU处理速度比GPU慢
• 解决方案：考虑升级到支持GPU的系统或使用较小的型号

性能提示

1. 使用GPU：确保CUDA兼容GPU具有足够的VRAM
2. 批处理：一起处理多个图像以提高效率
3. 模型选择：为您的硬件选择合适的型号尺寸
4. 图像大小：处理前调整大图像大小以节省内存
5. 缓存管理：模型在首次下载后缓存

获取帮助

• 问题:
• 讨论:

🔧 发展

本地开发

# Clone the repository
git clone https://github.com/joeleaver/transparent-background-mcp.git
cd transparent-background-mcp

# Create virtual environment
uv venv .venv && source .venv/bin/activate

# Install in development mode with dev dependencies
uv pip install -e ".[dev]"

# Run tests
pytest

# Format code
black src/
isort src/

# Type checking
mypy src/

MCP检验员测试

# Test the server locally
transparent-background-mcp-server

# Test with MCP Inspector
npx @modelcontextprotocol/inspector transparent-background-mcp-server

测试GitHub安装

📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

🙏 致谢

• BEN2：背景擦除网络2，用于最先进的背景删除
• Ultralytics：YOLO11模型用于对象分割
• InSPyReNet：稳定的背景移除实施
• 模型上下文协议：人工智能工具集成框架

🔗 相关项目

• 模型上下文协议
• Ultralytics YOLO
• 透明背景

______________________________________________________________________

由...制作❤️ 对于AI社区来说。100%本地，100%私有，100%强大。