Rembg MCP

🚀 Rembg MCP 服务器

Rembg MCP 服务器是用于 rembg 背景去除库的 MCP（模型上下文协议）服务器。借助该服务器，你可以通过 Claude Code、Claude Desktop、Cursor 等支持 MCP 的工具，利用 AI 模型去除图像背景。

🚀 快速开始

🚀 一键安装

Linux/macOS

git clone <repository-url>
cd rembg-mcp
./setup.sh

Windows

git clone <repository-url>
cd rembg-mcp
setup.bat

安装脚本将自动完成以下操作：

• 检查是否满足 Python 3.10+ 的要求
• 创建虚拟环境
• 安装所有依赖项
• 配置 MCP 服务器
• 测试安装情况
• 引导你下载 AI 模型

🔧 手动安装

如果你更喜欢手动安装或需要自定义配置，可以按照以下步骤操作：

1. 创建虚拟环境：

python3 -m venv rembg
source rembg/bin/activate  # Linux/macOS
# 或者
rembg\Scripts\activate.bat  # Windows

2. 安装依赖项：

pip install --upgrade pip
pip install mcp "rembg[cpu,cli]" pillow
pip install -e .

3. 测试安装：

python test_server.py
python validate_setup.py

4. 下载 AI 模型：

./download_models.sh     # Linux/macOS
# 或者
python download_models.py  # Windows（在激活的虚拟环境中）

5. 如需 GPU 支持：

pip install -e ".[gpu]"

✨ 主要特性

• 🖼️ 图像处理：可对单张图像进行背景去除，也能对文件夹进行批量处理。
• 🤖 多种 AI 模型：支持 u2net、birefnet、isnet、sam 等多种专业模型。
• ⚡ 性能优化：通过复用模型会话，实现高效的批量处理。
• 🎨 高级选项：提供 Alpha 抠图、仅输出蒙版、自定义背景等功能。
• 🌍 跨平台支持：兼容 Windows、macOS 和 Linux 系统。
• 🔧 易于集成：可与 Claude Desktop、Claude Code CLI、Cursor IDE 等工具配合使用。

🔧 MCP 配置

Claude Desktop 设置

1. 找到你的 Claude Desktop 配置文件：

   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json
   • Linux：~/.config/Claude/claude_desktop_config.json

2. 添加 rembg 服务器配置：

{
  "mcpServers": {
    "rembg": {
      "command": "/path/to/rembg-mcp/start_server.sh",
      "cwd": "/path/to/rembg-mcp",
      "env": {
        "REMBG_HOME": "~/.u2net",
        "OMP_NUM_THREADS": "4"
      }
    }
  }
}

3. 将 /path/to/rembg-mcp 替换为你实际的项目路径

4. 重启 Claude Desktop

测试配置

配置完成后，你可以对 MCP 服务器进行测试：

1. 手动启动服务器：

./start_server.sh  # Linux/macOS
# 或者
start_server.bat   # Windows

2. 在 Claude Desktop 中验证 MCP 连接：

   • 在 Claude 对话中查找 rembg 工具。
   • 尝试输入简单命令："List available MCP tools"。

3. 使用示例图像进行测试：

   • 向 Claude 提问："Use rembg-i to remove the background from test.jpg"。
   • 服务器将处理你的请求并返回结果。

Claude Code CLI 设置

在你的 Claude Code 设置中添加以下内容：

{
  "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 设置

在你的 Cursor 设置或工作区的 .cursor/settings.json 文件中添加以下内容：

{
  "mcp.servers": {
    "rembg": {
      "command": "/path/to/rembg-mcp/start_server.sh",
      "args": [],
      "cwd": "/path/to/rembg-mcp"
    }
  }
}

Windows 配置

对于 Windows 用户，请使用 start_server.bat 代替：

{
  "mcpServers": {
    "rembg": {
      "command": "C:\\path\\to\\rembg-mcp\\start_server.bat",
      "cwd": "C:\\path\\to\\rembg-mcp"
    }
  }
}

💻 使用示例

基础用法

单张图像处理：

Remove the background from my photo.jpg and save it as photo_nobg.png

批量处理：

Process all images in my Photos folder and remove their backgrounds

高级用法

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

🛠️ 可用的 MCP 工具

rembg-i - 单张图像背景去除

该工具可高精度地去除单张图像文件的背景。

必需参数：

• input_path：源图像文件的路径
• output_path：处理后图像的保存路径

可选参数：

• model：要使用的 AI 模型（默认为 "u2net"）
• alpha_matting：提高边缘质量（默认为 false）
• only_mask：仅输出黑白蒙版（默认为 false）

支持的格式： JPG、PNG、BMP、TIFF、WebP

rembg-p - 文件夹批量处理

该工具可自动处理文件夹中的所有图像。

必需参数：

• input_folder：包含图像的源文件夹
• output_folder：处理后图像的目标文件夹

可选参数：

• model：要使用的 AI 模型（默认为 "u2net"）
• alpha_matting：提高边缘质量（默认为 false）
• only_mask：仅输出蒙版（默认为 false）
• file_extensions：要处理的文件类型（默认为常见图像格式）

特性：

• 自动查找所有支持的图像
• 保留原始文件名，并添加 .out.png 后缀
• 提供详细的进度报告
• 对单个文件进行错误处理

🤖 支持的 AI 模型

🎯 模型推荐

初学者：建议从 u2net（默认）开始，它在速度和质量之间取得了良好的平衡。 追求最佳质量：使用 birefnet-general 或 birefnet-massive。 处理人像：使用 birefnet-portrait，它专为人物主体设计。 处理动漫/卡通图像：使用 isnet-anime，它针对动画内容进行了优化。 追求速度：使用 u2netp 或 silueta，它们在批量处理时速度更快。

📥 下载模型

模型在首次使用时会自动下载，但你也可以提前下载：

# 交互式选择（推荐）
./download_models.sh              # Linux/macOS

# 下载特定模型
./download_models.sh u2net birefnet-portrait

# 下载所有模型
./download_models.sh all

# Windows（在激活的虚拟环境中）
python download_models.py         # 交互式
python download_models.py u2net birefnet-portrait

模型会缓存到 ~/.u2net/ 目录中，只需下载一次。

🔧 配置

环境变量

• REMBG_HOME：模型存储目录（默认为 ~/.u2net）
• OMP_NUM_THREADS：用于处理的 CPU 线程数（默认为 4）
• MODEL_CHECKSUM_DISABLED：跳过模型校验和验证

高级选项

• Alpha 抠图：可提高边缘质量，但会增加处理时间。
• 仅输出蒙版：返回黑白蒙版，而非透明抠图。
• 自定义背景颜色：用纯色替换透明区域。
• 批量处理：自动复用模型会话，提高效率。

📁 项目结构

rembg-mcp/
├── rembg_mcp/
│   ├── __init__.py
│   └── server.py                      # 主 MCP 服务器实现
├── rembg/                             # 虚拟环境（git 忽略）
├── setup.sh                           # Linux/macOS 安装脚本
├── setup.bat                          # Windows 安装脚本
├── start_server.sh                    # Linux/macOS 服务器启动脚本
├── start_server.bat                   # Windows 服务器启动脚本（生成）
├── pyproject.toml                     # Python 包配置
├── claude_desktop_config.json         # Claude Desktop 配置（Linux/macOS）
├── claude_desktop_config_windows.json # Claude Desktop 配置（Windows）
├── test_server.py                     # 安装测试
├── validate_setup.py                  # 全面的安装验证
├── download_models.py                 # AI 模型下载工具（Python）
├── download_models.sh                 # AI 模型下载脚本（Linux/macOS）
├── example_usage.py                   # 使用示例
├── README.md                          # 本文件
├── USAGE_CN.md                       # 中文文档
└── CLAUDE.md                         # Claude Code 上下文文件

🚨 故障排除

常见问题

未找到 MCP 服务器

• 验证 MCP 配置中的 command 路径。
• 确保脚本可执行：chmod +x start_server.sh。
• 检查虚拟环境是否存在：ls rembg/。

Python 版本问题

python --version  # 必须为 3.10+
# 如果版本不正确，请安装 Python 3.10+ 并重新创建虚拟环境

模型下载问题

# 清除模型缓存并重新下载
rm -rf ~/.u2net

# 手动重新下载模型
./download_models.sh              # Linux/macOS
python download_models.py         # Windows

# 下载特定模型
./download_models.sh u2net        # Linux/macOS
python download_models.py u2net   # Windows

内存或性能问题

# 减少 CPU 线程数
export OMP_NUM_THREADS=2

# 使用轻量级模型（u2netp、silueta）代替大型模型

安装问题

# 清理并重新安装
rm -rf rembg/
./setup.sh  # 或者在 Windows 上使用 setup.bat

获取帮助

• 运行 python validate_setup.py 进行详细诊断。
• 手动启动服务器时检查服务器日志。
• 确保你的 MCP 客户端支持最新的协议版本。

📚 更多资源

• Rembg 库文档
• MCP 协议规范
• Claude Code 文档

🤝 贡献代码

1. 分叉仓库
2. 创建你的功能分支 (git checkout -b feature/amazing-feature)
3. 提交你的更改 (git commit -m 'Add amazing feature')
4. 将更改推送到分支 (git push origin feature/amazing-feature)
5. 打开一个拉取请求

📄 许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。

🙏 致谢

• danielgatis/rembg - 优秀的背景去除库
• Anthropic - 提供 MCP 协议和 Claude
• 开源社区提供的各种 AI 模型