Poof Background Removal MCP Server
This server lets AI assistants remove image backgrounds and check Poof account credits.
remove_background: Remove background from an image supplied as a base64 string or URL.
Choose output format: png, jpg, or webp.
Output rgba (transparent) or rgb (opaque, with optional bg_color).
Resize via size presets (full, preview, medium, hd) or exact width/ height.
Fit behavior with fit: contain, cover, or scale-down.
Optionally crop to subject bounds.
get_account: Show account plan, credit usage, remaining credits, and auto-recharge threshold.
Supports local stdio and remote HTTP/Cloudflare Worker transports.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Poof Background Removal MCP Server remove the background from https://example.com/portrait.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.
@poof-bg/mcp
MCP (Model Context Protocol) server for the Poof background removal API. Use AI assistants like Claude to remove backgrounds from images and videos.
Migrating from remove.bg? It shuts down on 1 December 2026 — see the remove.bg alternative and migration guide.
Features
remove_background - Remove background from images: PNG, JPEG, WebP or still GIF (accepts base64 or URL)
remove_video_background - Remove background from a video by URL: transparent WebM/MOV, green-screen MP4, looping transparent GIF or alpha matte, audio kept (except GIF)
get_job - Check the status of a video job and get its download link
get_account - Check your account info and credit balance
Supports both stdio (local) and HTTP (remote/Cloudflare Worker) transports
Related MCP server: Recraft MCP Server
Installation
Local (stdio transport)
npm install -g @poof-bg/mcpOr install locally:
git clone https://github.com/poof-bg/mcp.git
cd mcp
npm install
npm run buildRemote (HTTP transport via Cloudflare Worker)
The same tools are served over Streamable HTTP at https://api.poof.bg/mcp, with
OAuth 2.1 (sign in with your Poof account) or an x-api-key header. An OAuth
connection stays alive while it is used and expires after 30 days without use;
then the client asks you to log in again (in Codex, run codex mcp login poof).
Configuration
Environment Variable
Set your Poof API key:
export POOF_API_KEY=your_api_key_hereGet your API key at dash.poof.bg
Claude Code
OAuth (recommended)
claude mcp add --transport http poof https://api.poof.bg/mcpAPI Key
claude mcp add --transport http poof https://api.poof.bg/mcp \
--header "x-api-token: YOUR_POOF_API_KEY"Claude Desktop
Add to your Claude Desktop config file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Option 1: Remote with OAuth (recommended)
{
"mcpServers": {
"poof": {
"url": "https://api.poof.bg/mcp"
}
}
}Option 2: Local (stdio transport)
{
"mcpServers": {
"poof": {
"command": "npx",
"args": ["-y", "@poof-bg/mcp"],
"env": {
"POOF_API_KEY": "your_api_key_here"
}
}
}
}Option 3: Remote with API key
{
"mcpServers": {
"poof": {
"url": "https://api.poof.bg/mcp",
"headers": {
"x-api-token": "YOUR_POOF_API_KEY"
}
}
}
}Cursor
Add to .cursor/mcp.json in your project root (or global config):
OAuth (recommended)
{
"mcpServers": {
"poof": {
"url": "https://api.poof.bg/mcp"
}
}
}Local (stdio)
{
"mcpServers": {
"poof": {
"command": "npx",
"args": ["-y", "@poof-bg/mcp"],
"env": {
"POOF_API_KEY": "your_api_key_here"
}
}
}
}Remote with API key
{
"mcpServers": {
"poof": {
"url": "https://api.poof.bg/mcp",
"headers": {
"x-api-token": "YOUR_POOF_API_KEY"
}
}
}
}Windsurf
Add to ~/.codeium/windsurf/mcp_config.json:
OAuth (recommended)
{
"mcpServers": {
"poof": {
"serverUrl": "https://api.poof.bg/mcp"
}
}
}Local (stdio)
{
"mcpServers": {
"poof": {
"command": "npx",
"args": ["-y", "@poof-bg/mcp"],
"env": {
"POOF_API_KEY": "your_api_key_here"
}
}
}
}Remote with API key
{
"mcpServers": {
"poof": {
"serverUrl": "https://api.poof.bg/mcp",
"headers": {
"x-api-token": "YOUR_POOF_API_KEY"
}
}
}
}VS Code + Copilot
Add to your VS Code settings.json:
OAuth (recommended)
{
"mcp": {
"servers": {
"poof": {
"url": "https://api.poof.bg/mcp"
}
}
}
}Local (stdio)
{
"mcp": {
"servers": {
"poof": {
"command": "npx",
"args": ["-y", "@poof-bg/mcp"],
"env": {
"POOF_API_KEY": "your_api_key_here"
}
}
}
}
}Remote with API key
{
"mcp": {
"servers": {
"poof": {
"url": "https://api.poof.bg/mcp",
"headers": {
"x-api-token": "YOUR_POOF_API_KEY"
}
}
}
}
}Cline (VS Code Extension)
Open Cline settings and add to the MCP Servers configuration:
OAuth (recommended)
{
"poof": {
"url": "https://api.poof.bg/mcp"
}
}Local (stdio)
{
"poof": {
"command": "npx",
"args": ["-y", "@poof-bg/mcp"],
"env": {
"POOF_API_KEY": "your_api_key_here"
}
}
}Remote with API key
{
"poof": {
"url": "https://api.poof.bg/mcp",
"headers": {
"x-api-token": "YOUR_POOF_API_KEY"
}
}
}Tools
remove_background
Remove the background from an image (PNG, JPEG, WebP or still GIF, up to 20 MB). Animated GIFs are videos: use remove_video_background. If one is sent here anyway, the tool returns the video job (poll it with get_job) instead of an image.
Parameters:
Parameter | Type | Required | Description |
| string | Yes | Base64-encoded image or URL to a PNG, JPEG, WebP or still GIF image |
| string | No | Output format: |
| string | No | Color channels: |
| string | No | Background color, e.g. |
| string | No | Output size preset: |
| boolean | No | Crop to subject bounds (default: |
| integer | No | Output width in pixels (1-6000). Alone, the height follows the aspect ratio |
| integer | No | Output height in pixels (1-6000). Alone, the width follows the aspect ratio |
| string | No | How to fit into |
Example prompts:
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 centredResponse: the processed image as an MCP image content block (so the
assistant can show and look at it), followed by a text block with the metadata:
{ "success": true, "format": "png", "width": 1024, "height": 768, "processing_time_ms": 412 }remove_video_background
Remove the background from a video. Pass a public URL; the result is a direct download link that stays valid for 24 hours. Video costs 5 credits per second, rounded up (10 per second above 30 fps; animated GIFs are always 5 per second whatever their frame rate). Credits are charged when the job is accepted and refunded if it fails.
Parameters:
Parameter | Type | Required | Description |
| string | Yes | Public |
| string | No | Output container: |
| string | No |
|
| string | No | Background color, e.g. |
| string | No | Output size preset: |
| boolean | No | Poll until the job finishes, up to 50 seconds, before returning (default: |
Example prompts:
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 audioResponse:
{
"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"
}
}If the job is still running after 50 seconds, status is queued or processing, result_url is null and a hint tells the assistant to call get_job.
get_job
Check a video job started with remove_video_background. Polling is free.
Parameters:
Parameter | Type | Required | Description |
| string | Yes | The job id ( |
Example prompts:
Is my video done yet?
Check job job_8f3a1c2e9b7d4a10 and give me the download linkResponse: the same job object as above; result_url is set once status is completed, and error explains a failed job (failed jobs are refunded).
get_account
Get your account information and credit balance.
Example prompts:
Check my Poof account balance
How many credits do I have left?Response:
{
"success": true,
"data": {
"organizationId": "org_abc123",
"plan": "Pro",
"maxCredits": 5000,
"usedCredits": 1234,
"remainingCredits": 3766,
"autoRechargeThreshold": 100
}
}Errors
A failed call is returned as a tool result with isError: true and a readable
message (HTTP status, error code, details, documentation link and request ID),
so the assistant can see what went wrong. Messages say whether retrying can help:
used-up credits, an invalid API key, an unsupported image or video, or a URL Poof
could not download say not to retry the same input.
Rate limits (429) and temporary processing errors (502/503/504) are retried
twice with backoff before they are reported.
Development
Requests to the Poof API send a User-Agent of the form
poof-mcp/<version> (<client>; <transport>), e.g. poof-mcp/1.5.2 (Claude-ClaudeAI; hosted),
so usage can be attributed to the AI client that made it.
Release with npm version <patch|minor|major>, which also updates 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 formatDeployment (Cloudflare Worker)
To deploy the MCP server as a Cloudflare Worker:
# Install Wrangler if you haven't already
npm install -g wrangler
# Login to Cloudflare
wrangler login
# Deploy
wrangler deploySet the required environment secrets:
wrangler secret put POOF_API_KEY
wrangler secret put MCP_JWT_SECRET
wrangler secret put COOKIE_ENCRYPTION_KEYAlso set the dashboard URL variable:
wrangler secret put DASHBOARD_URLFor the ChatGPT app directory, set the domain verification token OpenAI issues as
OPENAI_APPS_CHALLENGE_TOKEN (served at /.well-known/openai-apps-challenge):
wrangler secret put OPENAI_APPS_CHALLENGE_TOKENYou'll also need to create a KV namespace for OAuth state storage and update the IDs in wrangler.toml:
wrangler kv namespace create OAUTH_KV
wrangler kv namespace create OAUTH_KV --previewLicense
MIT
Links
Available Tools
2 toolsget_accountBInspect
Get account information including plan details and credit usage
Inputs: no named parameters.
remove_backgroundAInspect
Remove the background from an image. Returns the processed image as base64. Accepts URL or base64-encoded image. Can also resize the result to an exact width x height without stretching (width, height, fit).
Inputs: image (required), fit, crop, size, +5 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 2 tools
The two tools have clearly distinct purposes: one handles account/plan information and the other performs the core background removal operation. There is no overlap or ambiguity between them.
Both tools follow a consistent verb_noun snake_case pattern: get_account and remove_background. The naming is predictable and immediately conveys each tool's action and target.
With only two tools, the server feels minimal but appropriate for a focused single-purpose service. The account tool supports the main workflow, yet the surface is borderline thin compared to the typical well-scoped range.
The core background removal workflow is fully covered, including input via URL or base64 and optional resizing. Account and credit information is also available, though there are minor missing conveniences such as batch processing or output format options.
Maintenance
Related MCP Connectors
Remove image backgrounds with U2NetP and return transparent PNG pixels without identifying metadata
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.
Remove photo backgrounds to transparent, white, or solid color. $0.01/image; 10 free per day.
Image and video AI tools and your own pipelines, run from any AI assistant.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables AI-powered background removal from images using multiple specialized models including u2net, birefnet, and isnet. Supports both single image processing and batch folder operations with advanced options like alpha matting and mask-only output.25MIT
- AlicenseBqualityBmaintenanceEnables background removal and upscaling of images using Recraft models via RunAPI, with task polling and pricing lookup.553 npmApache 2.0
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to interactively remove image backgrounds using a Paint.NET-style magic wand tool with live visual feedback and precision helpers.MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI-powered removal of image backgrounds from URLs, returning transparent PNGs with optional solid color replacement or resizing.MIT