Skip to main content
Glama
poof-bg

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

NameRequiredDescriptionDefault

No parameters

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. While 'Get' implies a read operation, the description doesn't specify whether this requires authentication, has rate limits, returns real-time or cached data, or what format the information comes in. For a tool with zero annotation coverage, this represents significant gaps in behavioral transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is perfectly concise - a single sentence that efficiently communicates the tool's purpose without any wasted words. It's front-loaded with the core functionality and includes specific details about what information is retrieved.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read operation with no parameters, the description covers the basic purpose adequately. However, with no annotations and no output schema, the description doesn't address important behavioral aspects like authentication requirements, response format, or data freshness. The description is complete enough for the tool's simplicity but leaves gaps in operational context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, and schema description coverage is 100% (though trivial since there are no parameters). The description appropriately doesn't discuss parameters since none exist. A baseline of 4 is appropriate for a zero-parameter tool where the schema fully documents the parameter situation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with a specific verb ('Get') and resource ('account information'), including what information is retrieved ('plan details and credit usage'). It doesn't differentiate from its only sibling 'remove_background', but that's reasonable since they serve completely different functions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. While there's only one sibling tool ('remove_background') that serves a completely different purpose, the description doesn't mention any prerequisites, constraints, or contextual factors for using this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

NameRequiredDescriptionDefault
fitNoHow to fit the image into width x height. 'contain' pads the remaining area (transparent or bg_color), 'cover' fills the canvas and crops the overflow around the subject, 'scale-down' is like contain but never enlarges a smaller imagecontain
cropNoWhether to crop the image to the subject bounds
sizeNoOutput image size preset (megapixel cap). Ignored when width or height is setfull
imageYesImage input: base64-encoded image data or a URL to an image
widthNoOutput width in pixels. On its own, the height follows the aspect ratio. With height, the image is fitted into an exact width x height canvas without stretching
formatNoOutput image formatpng
heightNoOutput height in pixels. On its own, the width follows the aspect ratio. With width, the image is fitted into an exact width x height canvas without stretching
bg_colorNoBackground color (hex, rgb, or color name). Only applies when channels is 'rgb'. Example: '#ffffff'
channelsNoOutput color channels. Use 'rgba' for transparency, 'rgb' for opaque backgroundrgba

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It does disclose key behavioral traits: 'Returns the processed image as base64' and 'Accepts URL or base64-encoded image.' However, it does not mention potential error conditions, limits, side effects, or whether the operation is stateless. It adds some behavioral transparency but not comprehensive context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with no filler. The primary purpose is front-loaded, followed by output format, input types, and optional resizing capability. Every sentence contributes useful information, and the structure makes it easy to scan.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 9 parameters and no output schema, the description provides a complete high-level view: what it does, accepted inputs, return format, and the key resizing behavior. The schema supplies detailed parameter semantics, so the description need not repeat them. It lacks explicit error handling or limitations, but the essential information for correct invocation is present.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description mentions width, height, and fit in passing but does not add meaning beyond the schema's detailed parameter descriptions. The schema already fully documents each parameter, so the description adds minimal additional semantic value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb and resource: 'Remove the background from an image.' It clearly distinguishes itself from the only sibling, get_account, which serves a completely different purpose. The statement is unambiguous and instantly conveys the tool's core function.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context about when to use the tool: whenever background removal is needed. It states the accepted input types (URL or base64) and the available resizing behavior, giving enough context for an agent to select it. It does not explicitly mention when not to use it or list alternatives, but no close alternatives exist among siblings, so this is a minor gap.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 1 tool updatev1.2.0
    • Changedremove_background5 fields changed
      • addedInput schema / properties / fit
        Added value: +{
        +  "default": "contain",
        +  "description": "How to fit the image into width x height. 'contain' pads the remaining area (transparent or bg_color), 'cover' fills the canvas and crops the overflow around the subject, 'scale-down' is like contain but never enlarges a smaller image",
        +  "enum": [
        +    "contain",
        +    "cover",
        +    "scale-down"
        +  ],
        +  "type": "string"
        +}
      • addedInput schema / properties / height
        Added value: +{
        +  "description": "Output height in pixels. On its own, the width follows the aspect ratio. With width, the image is fitted into an exact width x height canvas without stretching",
        +  "maximum": 6000,
        +  "minimum": 1,
        +  "type": "integer"
        +}
      • changedInput schema / properties / size / description
        Previous value: -"Output image size preset"New value: +"Output image size preset (megapixel cap). Ignored when width or height is set"
      • changedInput schema / properties / size / enum
        Previous value: -[
        -  "full",
        -  "preview",
        -  "small",
        -  "medium",
        -  "large"
        -]New value: +[
        +  "full",
        +  "preview",
        +  "medium",
        +  "hd"
        +]
      • addedInput schema / properties / width
        Added value: +{
        +  "description": "Output width in pixels. On its own, the height follows the aspect ratio. With height, the image is fitted into an exact width x height canvas without stretching",
        +  "maximum": 6000,
        +  "minimum": 1,
        +  "type": "integer"
        +}
  2. 2 tool updatesv1.1.0
    • First observedget_account
    • First observedremove_background

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

ActivityMaintained
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers