Skip to main content
Glama
Poof Background Removal MCP Server

Poof Background Removal MCP Server

by poof-bg

@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/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

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

{
  "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):

{
  "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:

{
  "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:

{
  "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:

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

image

string

Yes

Base64-encoded image or URL to a PNG, JPEG, WebP or still GIF image

format

string

No

Output format: png, jpg, webp (default: png)

channels

string

No

Color channels: rgba for transparency, rgb for opaque (on bg_color, white by default), alpha for the grayscale alpha mask only (default: rgba)

bg_color

string

No

Background color, e.g. #ffffff. Setting it fills the background, so the result is opaque; with rgb channels or jpg format and no bg_color the background is white. Ignored with channels: alpha

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

video_url

string

Yes

Public https URL of the video (mp4, mov, webm, m4v, mkv or animated gif; up to 500 MB and 5 minutes)

format

string

No

Output container: webm (VP9, transparent unless bg_color is set), mov (ProRes 4444, transparent unless bg_color is set), mp4 (H.264, composited onto bg_color), gif (looping GIF, 1-bit transparency, no audio, capped at 1280 px on the longest side (720p for widescreen) and 50 fps; size: preview for sticker-sized output) (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, e.g. #00ff00. Setting it fills the background, so the result is opaque in every format (webm, mov and gif included); with rgb or mp4 and no bg_color the background is white. Ignored with channels: alpha

size

string

No

Output size preset: full, preview (640), medium (1280), hd (1920) (default: full, source resolution up to 4K)

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

Available Tools

2 tools
get_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

    A3.7/5.0

    Scored across 2 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count3/5

    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.

    Completeness4/5

    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

    ActivityNo data
    ResponsivenessSyncing

    Related MCP Connectors

    Related MCP Servers