Poof

@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

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 (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:

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, 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:

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:

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, 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 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

Links

• Poof Website
• API Documentation
• Dashboard
• MCP Protocol