bgremover-mcp
# 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
Scored across 7 tools
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.
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.
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.
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.