Poof

Hintergrundentfernungs-API – entfernt Hintergründe aus Bildern mit einem einfachen API-Aufruf. Unterstützt PNG-, JPEG- und WebP-Ausgabe mit Transparenz oder benutzerdefinierten Hintergründen.

GitHub

Dokumentation

@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 (accepts base64 or URL)
remove_video_background - Remove background from a video by URL: transparent WebM/MOV, green-screen MP4 or alpha matte, audio kept
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

Installation

Local (stdio transport)

npm install -g @poof-bg/mcp

Or install locally:

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

Remote (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_here

Get your API key at dash.poof.bg

Claude Code

OAuth (recommended)

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

API 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.

Parameters:

Parameter	Type	Required	Description
`image`	string	Yes	Base64-encoded image or URL to an image
`format`	string	No	Output format: `png`, `jpg`, `webp` (default: `png`)
`channels`	string	No	Color channels: `rgba` for transparency, `rgb` for opaque (default: `rgba`)
`bg_color`	string	No	Background color when using `rgb` channels (e.g., `#ffffff`)
`size`	string	No	Output size preset: `full`, `preview`, `medium`, `hd` (default: `full`). Ignored when `width`/`height` is set
`crop`	boolean	No	Crop to subject bounds (default: `false`)
`width`	integer	No	Output width in pixels (1-6000). Alone, the height follows the aspect ratio
`height`	integer	No	Output height in pixels (1-6000). Alone, the width follows the aspect ratio
`fit`	string	No	How to fit into `width` x `height` without stretching: `contain` (default, pad), `cover` (fill, crop the overflow around the subject), `scale-down` (pad, never enlarge)

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 centred

Response: 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.

Parameters:

Parameter	Type	Required	Description
`video_url`	string	Yes	Public `https` URL of the video (mp4, mov, webm or mkv; up to 500 MB and 5 minutes)
`format`	string	No	Output container: `webm` (VP9, transparent), `mov` (ProRes 4444, transparent), `mp4` (H.264, composited onto `bg_color`) (default: `webm`)
`channels`	string	No	`rgba` for transparency, `rgb` for an opaque background, `alpha` for a grayscale matte video (default: `rgba`)
`bg_color`	string	No	Background color when the output has no transparency (`rgb` or `mp4`), e.g. `#00ff00` (default: white)
`size`	string	No	Output size preset: `full`, `preview` (640), `medium` (1280), `hd` (1920) (default: `full`, capped at 1080p)
`wait`	boolean	No	Poll until the job finishes, up to 50 seconds, before returning (default: `true`). Set `false` to get the job id back immediately

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 audio

Response:

{
  "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
`job_id`	string	Yes	The job id (`job_...`)

Example prompts:

Is my video done yet?

Check job job_8f3a1c2e9b7d4a10 and give me the download link

Response: 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 or an unsupported image say not to retry. 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.4.0 (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 format

Deployment (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 deploy

Set the required environment secrets:

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

Also set the dashboard URL variable:

wrangler secret put DASHBOARD_URL

For 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_TOKEN

You'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 --preview

License

MIT

Poof

Dokumentation

@poof-bg/mcp

Features

Installation

Local (stdio transport)

Remote (HTTP transport via Cloudflare Worker)

Configuration

Environment Variable

Claude Code

OAuth (recommended)

API Key

Claude Desktop

Option 1: Remote with OAuth (recommended)

Option 2: Local (stdio transport)

Option 3: Remote with API key

Cursor

OAuth (recommended)

Local (stdio)

Remote with API key

Windsurf

OAuth (recommended)

Local (stdio)

Remote with API key

VS Code + Copilot

OAuth (recommended)

Local (stdio)

Remote with API key

Cline (VS Code Extension)

OAuth (recommended)

Local (stdio)

Remote with API key

Tools

remove_background

remove_video_background

get_job

get_account

Errors

Development

Deployment (Cloudflare Worker)

License

Links