Skip to main content
Glama
README.md
# bgremover-mcp

Model Context Protocol (MCP) server for [BGRemover Video](https://www.bgremover.video).
It lets Claude Desktop, Claude Code, Cursor, and other MCP clients remove or replace
the background of videos and images.

```text
MCP client -> bgremover-mcp -> https://www.bgremover.video/api/v1/* -> BGRemover backend
```

The server only calls the public `/api/v1` API. It never touches internal routes,
FastAPI/RunPod URLs, S3 buckets, or the database.

## Tools

| Tool | Endpoint | Notes |
| --- | --- | --- |
| `remove_video_background` | `POST /videos/remove-background` | Async. Transparent, solid color, or image background. |
| `remove_image_background` | `POST /images/remove-background` | Synchronous, 1 credit. |
| `get_job_status` | `GET /jobs/{job_id}` | `queued` / `processing` / `completed` / `failed`; `output_url` when done. |
| `check_credits` | `GET /me/credits` | |
| `list_features` | `GET /features` | |
| `upload_image`, `upload_video` | `POST /uploads/{image,video}` | stdio server only (reads local files). |

Video credits: `ceil(duration_seconds) * 1.5`, doubled for watermark-free exports on
accounts that have never purchased credits. If `duration_seconds` is omitted the
backend measures the video; it never guesses.

## Use it

### Local (stdio)

Create an API key at https://www.bgremover.video/developers, then:

```json
{
  "mcpServers": {
    "bgremover": {
      "command": "npx",
      "args": ["-y", "bgremover-mcp"],
      "env": { "BGREMOVER_API_KEY": "vbr_..." }
    }
  }
}
```

### Remote (HTTP + OAuth)

`https://mcp.bgremover.video/mcp` accepts either a `vbr_` API key as a Bearer token or
an OAuth 2.1 token (authorization code + PKCE, dynamic client registration) issued by
bgremover.video, so web Claude and ChatGPT can connect without handling keys.

## Development

```bash
npm install
npm run typecheck
npm test
npm run build
npm run dev          # stdio, needs BGREMOVER_API_KEY
npm run dev:http     # HTTP server on :3000
```

See `.env.example` for configuration.

## Notes

- Developer API keys default to 100 calls/day and 1000/month on the website. Every
  tool call, including `get_job_status` polling, counts toward that limit.
- Keys created through the OAuth flow have no call limits and expire after 7 days
  (refreshed automatically via refresh tokens).
# bgremover-mcp

TDQS

A4/5.0

Scored across 7 tools

Disambiguation5/5

Each tool targets a clearly distinct action and resource: uploads are split by media type, background removal is split by media type, and job status is a single-purpose polling tool. The video/image pairs are near-parallel but unambiguously named and scoped, so an agent can select correctly without guessing.

Naming Consistency5/5

All seven tools use a consistent snake_case verb_noun pattern (upload_image, check_credits, remove_video_background, get_job_status). No mixed conventions or vague verbs anywhere in the set.

Tool Count5/5

Seven tools is well-scoped for a background-removal service: two uploads, two processing operations, one async poller, and two account/introspection utilities. Every tool earns its place with no redundancy.

Completeness4/5

The core lifecycle (upload -> process -> poll result) plus credits and feature discovery is covered for both image and video. Minor gaps remain: no job cancellation, no listing of past jobs or uploaded assets, and no cleanup/delete for uploaded files.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues