Poof

@poof-bg/mcp

用于 Poof 背景移除 API 的 MCP（Model Context Protocol）服务。使用 Claude 等 AI 助手移除图像和视频的背景。

要从 remove.bg 迁移？该服务将于 2026 年 12 月 1 日关闭——请参阅 remove.bg 替代方案和迁移指南。

功能

• remove_background - 移除图像背景：支持 PNG、JPEG、WebP 或静态 GIF（接受 base64 或 URL）
• remove_video_background - 根据 URL 移除视频背景：支持透明 WebM/MOV、绿幕 MP4、循环透明 GIF 或 alpha matte，并保留音频（GIF 除外）
• get_job - 查看视频任务状态并获取下载链接
• get_account - 查看账户信息和积分余额
• 支持 stdio（本地）和 HTTP（远程/Cloudflare Worker）传输方式

安装

本地（stdio 传输）

npm install -g @poof-bg/mcp

或在本地安装：

git clone https://github.com/poof-bg/mcp.git
cd mcp
npm install
npm run build

远程（通过 Cloudflare Worker 使用 HTTP 传输）

相同的工具通过 Streamable HTTP 在 https://api.poof.bg/mcp 上提供，支持 OAuth 2.1（使用 Poof 账户登录）或 x-api-key 标头。OAuth 连接在使用期间会保持有效，闲置 30 天后过期；此时客户端会要求你重新登录（在 Codex 中，运行 codex mcp login poof）。

配置

环境变量

设置 Poof API 密钥：

export POOF_API_KEY=your_api_key_here

前往 dash.poof.bg 获取 API 密钥

Claude Code

OAuth（推荐）

claude mcp add --transport http poof https://api.poof.bg/mcp

API 密钥

claude mcp add --transport http poof https://api.poof.bg/mcp \
  --header "x-api-token: YOUR_POOF_API_KEY"

Claude Desktop

将配置添加到 Claude Desktop 配置文件：

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

选项 1：使用 OAuth 远程连接（推荐）

{
  "mcpServers": {
    "poof": {
      "url": "https://api.poof.bg/mcp"
    }
  }
}

选项 2：本地连接（stdio 传输）

{
  "mcpServers": {
    "poof": {
      "command": "npx",
      "args": ["-y", "@poof-bg/mcp"],
      "env": {
        "POOF_API_KEY": "your_api_key_here"
      }
    }
  }
}

选项 3：使用 API 密钥远程连接

{
  "mcpServers": {
    "poof": {
      "url": "https://api.poof.bg/mcp",
      "headers": {
        "x-api-token": "YOUR_POOF_API_KEY"
      }
    }
  }
}

Cursor

将配置添加到项目根目录下的 .cursor/mcp.json（或全局配置）：

OAuth（推荐）

{
  "mcpServers": {
    "poof": {
      "url": "https://api.poof.bg/mcp"
    }
  }
}

本地（stdio）

{
  "mcpServers": {
    "poof": {
      "command": "npx",
      "args": ["-y", "@poof-bg/mcp"],
      "env": {
        "POOF_API_KEY": "your_api_key_here"
      }
    }
  }
}

使用 API 密钥远程连接

{
  "mcpServers": {
    "poof": {
      "url": "https://api.poof.bg/mcp",
      "headers": {
        "x-api-token": "YOUR_POOF_API_KEY"
      }
    }
  }
}

Windsurf

将配置添加到 ~/.codeium/windsurf/mcp_config.json：

OAuth（推荐）

{
  "mcpServers": {
    "poof": {
      "serverUrl": "https://api.poof.bg/mcp"
    }
  }
}

本地（stdio）

{
  "mcpServers": {
    "poof": {
      "command": "npx",
      "args": ["-y", "@poof-bg/mcp"],
      "env": {
        "POOF_API_KEY": "your_api_key_here"
      }
    }
  }
}

使用 API 密钥远程连接

{
  "mcpServers": {
    "poof": {
      "serverUrl": "https://api.poof.bg/mcp",
      "headers": {
        "x-api-token": "YOUR_POOF_API_KEY"
      }
    }
  }
}

VS Code + Copilot

将配置添加到 VS Code 的 settings.json：

OAuth（推荐）

{
  "mcp": {
    "servers": {
      "poof": {
        "url": "https://api.poof.bg/mcp"
      }
    }
  }
}

本地（stdio）

{
  "mcp": {
    "servers": {
      "poof": {
        "command": "npx",
        "args": ["-y", "@poof-bg/mcp"],
        "env": {
          "POOF_API_KEY": "your_api_key_here"
        }
      }
    }
  }
}

使用 API 密钥远程连接

{
  "mcp": {
    "servers": {
      "poof": {
        "url": "https://api.poof.bg/mcp",
        "headers": {
          "x-api-token": "YOUR_POOF_API_KEY"
        }
      }
    }
  }
}

Cline（VS Code 扩展）

打开 Cline 设置，并将配置添加到 MCP Servers 配置中：

OAuth（推荐）

{
  "poof": {
    "url": "https://api.poof.bg/mcp"
  }
}

本地（stdio）

{
  "poof": {
    "command": "npx",
    "args": ["-y", "@poof-bg/mcp"],
    "env": {
      "POOF_API_KEY": "your_api_key_here"
    }
  }
}

使用 API 密钥远程连接

{
  "poof": {
    "url": "https://api.poof.bg/mcp",
    "headers": {
      "x-api-token": "YOUR_POOF_API_KEY"
    }
  }
}

---

工具

remove_background

从图像（PNG、JPEG、WebP 或静态 GIF，最大 20 MB）中移除背景。动画 GIF 属于视频：请使用 remove_video_background。如果仍将动画 GIF 发送到此工具，工具会返回视频任务（使用 get_job 轮询），而不是图像。

参数：

参数	类型	必填	描述
image	string	是	Base64 编码的图像，或指向 PNG、JPEG、WebP 或静态 GIF 图像的 URL
format	string	否	输出格式：png、jpg、webp（默认：png）
channels	string	否	颜色通道：rgba 表示透明，rgb 表示不透明（使用 bg_color，默认白色），alpha 表示仅输出灰度 Alpha 蒙版（默认：rgba）
bg_color	string	否	背景颜色，例如 #ffffff。设置此项会填充背景，因此结果为不透明；使用 rgb 通道或 jpg 格式且未设置 bg_color 时，背景为白色。与 channels: alpha 一起使用时会被忽略
size	string	否	输出尺寸预设：full、preview、medium、hd（默认：full）。设置 width/height 时会被忽略
crop	boolean	否	裁剪至主体边界（默认：false）
width	integer	否	输出宽度，单位为像素（1-6000）。单独设置时，高度会按宽高比调整
height	integer	否	输出高度，单位为像素（1-6000）。单独设置时，宽度会按宽高比调整
fit	string	否	如何在不拉伸的情况下适配 width x height：contain（默认，填充留白）、cover（填满，裁剪主体周围超出的部分）、scale-down（填充留白，绝不放大）

示例提示词：

Remove the background from this image: https://example.com/photo.jpg

Remove the background and add a white background instead

Remove the background and give me a 500x500 image with the product centred

**响应：**处理后的图像作为 MCP image 内容块返回（以便助手展示和查看），后接包含元数据的文本块：

{ "success": true, "format": "png", "width": 1024, "height": 768, "processing_time_ms": 412 }

remove_video_background

从视频中移除背景。传入公开 URL；结果为直接下载链接，有效期为 24 小时。视频每秒消耗 5 个额度，按秒向上取整（帧率高于 30 fps 时每秒消耗 10 个额度；动画 GIF 无论帧率如何，每秒始终消耗 5 个额度）。任务被接受时会扣除额度，若任务失败则退还。

参数：

参数	类型	必填	描述
video_url	string	是	视频的公开 https URL（mp4、mov、webm、m4v、mkv 或动画 GIF；最大 500 MB，时长不超过 5 分钟）
format	string	否	输出容器：webm（VP9，除非设置 bg_color，否则透明）、mov（ProRes 4444，除非设置 bg_color，否则透明）、mp4（H.264，合成到 bg_color 上）、gif（循环播放的 GIF，1 位透明，无音频，最长边限制为 1280 px（宽屏为 720p），帧率上限为 50 fps；使用 size: preview 可输出贴纸尺寸）（默认：webm）
channels	string	否	rgba 表示透明，rgb 表示不透明背景，alpha 表示灰度蒙版视频（默认：rgba）
bg_color	string	否	背景颜色，例如 #00ff00。设置此项会填充背景，因此所有格式（包括 webm、mov 和 gif）的结果都将不透明；使用 rgb 或 mp4 且未设置 bg_color 时，背景为白色。与 channels: alpha 一起使用时会被忽略
size	string	否	输出尺寸预设：full、preview（640）、medium（1280）、hd（1920）（默认：full，源分辨率最高支持 4K）
wait	boolean	否	返回前轮询任务，直到任务完成，最多等待 50 秒（默认：true）。设为 false 可立即返回任务 ID

示例提示词：

Remove the background from this video: https://example.com/clip.mp4

Turn https://example.com/clip.mov into a transparent WebM

Give me a green-screen MP4 of this video and keep the audio

响应：

{
  "success": true,
  "job": {
    "id": "job_8f3a1c2e9b7d4a10",
    "status": "completed",
    "progress": 1,
    "duration_seconds": 12.4,
    "fps": 29.97,
    "width": 1920,
    "height": 1080,
    "frames": 372,
    "credits": 65,
    "format": "webm",
    "channels": "rgba",
    "result_url": "https://cdn.poof.bg/1d/jobs/job_8f3a1c2e9b7d4a10/result.webm",
    "expires_at": "2026-10-17T10:12:00Z"
  }
}

如果任务在 50 秒后仍在运行，status 为 queued 或 processing，result_url 为 null，并且 hint 会提示助手调用 get_job。

get_job

检查通过 remove_video_background 启动的视频任务。轮询免费。

参数：

参数	类型	必填	描述
job_id	string	是	任务 ID（job_...）

示例提示词：

Is my video done yet?

Check job job_8f3a1c2e9b7d4a10 and give me the download link

响应： 与上述相同的 job 对象；当 status 为 completed 时会设置 result_url，error 会说明任务失败的原因（失败的任务会退款）。

get_account

获取账户信息和额度余额。

示例提示词：

Check my Poof account balance

How many credits do I have left?

响应：

{
  "success": true,
  "data": {
    "organizationId": "org_abc123",
    "plan": "Pro",
    "maxCredits": 5000,
    "usedCredits": 1234,
    "remainingCredits": 3766,
    "autoRechargeThreshold": 100
  }
}

错误

调用失败时会返回一条带有 isError: true 的工具结果，并附上易于理解的消息（HTTP 状态、错误代码、详情、文档链接和请求 ID），让助手了解出了什么问题。消息会说明重试是否有帮助：额度用尽、API 密钥无效、图像或视频不受支持，或 Poof 无法下载的 URL，都会提示不要使用相同输入重试。 速率限制（429）和临时处理错误（502/503/504）会先通过退避机制重试两次，然后再报告。

---

开发

向 Poof API 发送请求时会使用如下格式的 User-Agent： poof-mcp/<version> (<client>; <transport>)，例如 poof-mcp/1.5.2 (Claude-ClaudeAI; hosted)， 以便将用量归因到发起请求的 AI 客户端。

使用 npm version <patch|minor|major> 发布，同时也会更新 src/version.ts。

# Install dependencies
npm install

# Build
npm run build

# Run in dev mode (Cloudflare Worker)
npm run dev

# Run locally (stdio mode)
POOF_API_KEY=your_key npm start

# Test
npm test

# Lint
npm run lint

# Format
npm run format

部署（Cloudflare Worker）

要将 MCP 服务部署为 Cloudflare Worker：

# Install Wrangler if you haven't already
npm install -g wrangler

# Login to Cloudflare
wrangler login

# Deploy
wrangler deploy

设置所需的环境密钥：

wrangler secret put POOF_API_KEY
wrangler secret put MCP_JWT_SECRET
wrangler secret put COOKIE_ENCRYPTION_KEY

同时设置控制面板 URL 变量：

wrangler secret put DASHBOARD_URL

对于 ChatGPT 应用目录，将 OpenAI 签发的域名验证令牌设置为 OPENAI_APPS_CHALLENGE_TOKEN（通过 /.well-known/openai-apps-challenge 提供）：

wrangler secret put OPENAI_APPS_CHALLENGE_TOKEN

你还需要创建一个用于存储 OAuth 状态的 KV 命名空间，并更新 wrangler.toml 中的 ID：

wrangler kv namespace create OAUTH_KV
wrangler kv namespace create OAUTH_KV --preview

许可证

MIT

链接

• Poof 网站
• API 文档
• 控制面板
• MCP 协议