What is the Model Context Protocol (MCP)?

The Model Context Protocol (MCP) is an open standard that defines how applications provide context to Large Language Models (LLMs). It enables AI models to seamlessly interact with diverse data sources and tools, acting as a universal connector between AI agents and external services.

Which AI agents support BGBlur MCP integration?

BGBlur MCP server works with Claude Desktop, Claude Code, Cursor, and any other MCP-compatible AI agent. It supports both local SSE transport and remote HTTP/HTTPS deployment.

How do I authenticate with the BGBlur MCP server?

Authentication uses bearer tokens. Generate an API key from your BGBlur developer dashboard and provide it as BGBLUR_API_KEY in your environment configuration or MCP settings.

Can I deploy the BGBlur MCP server remotely?

Yes, BGBlur MCP server supports remote deployment on Docker, Railway, Render, Fly.io, Google Cloud Run, and other containerized platforms. The official hosted endpoint is https://mcp.bgblur.com/mcp

Developer Integration

Model Context Protocol (MCP)

Connect BGBlur video and image processing to Claude Desktop, Claude Code, Cursor, and other MCP-compatible AI agents.

View on GitHub Generate API Key

Capabilities

Extend your AI agents with professional-grade video and image processing through the Model Context Protocol.

Background Processing

Blur or remove backgrounds from images and videos with transparency support and depth effects.

Image background blur
Video background blur
Background removal with alpha channel
Portrait enhancement with depth

Privacy & Anonymization

Detect and blur faces, license plates, and sensitive content to ensure privacy compliance.

Face detection and blurring
License plate detection and blur
Object removal from videos
NSFW content detection

Async Job Management

Submit processing jobs and monitor status with webhooks and polling for large media files.

Job status monitoring
Webhook notifications
Credit balance checking
Batch processing support

Developer Experience

Clean API with local file upload, comprehensive error handling, and multi-platform deployment.

Local file upload support
Feature discovery and schema
TypeScript definitions
Docker containerization

Integration Guide

Complete documentation for connecting BGBlur to your AI agents and deploying the MCP server.

Overview

The BGBlur MCP server is an official Model Context Protocol implementation that enables Claude Desktop, Claude Code, Cursor, and other MCP-compatible AI agents to leverage BGBlur's professional video and image processing capabilities. The server acts as a lightweight client exclusively calling BGBlur's public API endpoints (https://bgblur.com/api/v1/*), ensuring a stable, production-ready integration without exposing internal implementation details.

Authentication

All requests to the BGBlur MCP server use bearer token authentication. Generate an API key from your developer dashboard and configure it in your MCP client settings or environment variables.

Config

# Environment Configuration
BGBLUR_API_KEY=vba_your_api_key_here
BGBLUR_API_BASE_URL=https://bgblur.com/api/v1

# Authorization Header (handled automatically)
Authorization: Bearer vba_your_api_key

Installation - Claude Desktop

To integrate BGBlur MCP with Claude Desktop, clone the repository, build the server, and add it to your Claude Desktop MCP configuration file.

Config

# 1. Clone and build
git clone https://github.com/whyashthakker/bgblur-mcp.git
cd bgblur-mcp
npm install
npm run build

# 2. Add to Claude Desktop config
# Location: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
# Location: %APPDATA%\Claude\claude_desktop_config.json (Windows)

{
  "mcpServers": {
    "bgblur": {
      "command": "node",
      "args": ["/absolute/path/to/bgblur-mcp/dist/server.js"],
      "env": {
        "BGBLUR_API_KEY": "vba_your_api_key"
      }
    }
  }
}

Remote Deployment - Hosted Endpoint

BGBlur provides an official hosted MCP server endpoint that can be connected to any MCP-compatible client without local installation. This is ideal for teams and production deployments.

Config

# Claude Desktop Configuration (Remote)
{
  "mcpServers": {
    "bgblur": {
      "url": "https://mcp.bgblur.com/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer vba_your_api_key"
      }
    }
  }
}

# Claude Code / Cursor Configuration
# Add to .claude/mcp.json or cursor MCP settings
{
  "servers": {
    "bgblur": {
      "url": "https://mcp.bgblur.com/mcp",
      "auth": "Bearer vba_your_api_key"
    }
  }
}

Docker Deployment

Deploy the BGBlur MCP server as a containerized service on any cloud platform supporting Docker. This provides a self-hosted alternative with full control over scaling and networking.

Config

# Dockerfile (included in repository)
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY dist ./dist
EXPOSE 3000
CMD ["node", "dist/server.js"]

# Build and run
docker build -t bgblur-mcp .
docker run -p 3000:3000 \
  -e BGBLUR_API_KEY=vba_your_api_key \
  -e NODE_ENV=production \
  bgblur-mcp

# Docker Compose
version: '3.8'
services:
  bgblur-mcp:
    image: bgblur-mcp
    ports:
      - "3000:3000"
    environment:
      - BGBLUR_API_KEY=${BGBLUR_API_KEY}
      - BGBLUR_API_BASE_URL=https://bgblur.com/api/v1

Available Tools

The BGBlur MCP server exposes the following tools to AI agents. All tools support both synchronous and asynchronous processing with job status monitoring.

Config

# Core Processing Tools
- blur_background_image       # Blur image backgrounds
- blur_background_video       # Blur video backgrounds
- remove_background_image     # Remove with transparency
- enhance_portrait            # Portrait enhancement
- blur_faces_image            # Face detection and blur
- blur_faces_video            # Video face anonymization
- blur_license_plates         # License plate detection
- remove_object_video         # Object removal
- detect_nsfw                 # NSFW content detection

# Utility Tools
- check_job_status           # Monitor processing jobs
- get_credit_balance         # Check API credits
- list_features              # Discover capabilities
- get_tool_schema            # Tool documentation

Security Best Practices

When integrating the BGBlur MCP server, follow these security guidelines to protect your API credentials and ensure safe operation.

Never hard-code API keys in configuration files committed to version control
Use environment variables or secret management services (AWS Secrets Manager, HashiCorp Vault)
Validate all inputs and file paths before processing
Implement rate limiting and quota monitoring in production deployments
Use HTTPS for all remote MCP server connections
Rotate API keys regularly and immediately revoke compromised credentials
Monitor API usage through the developer dashboard
Return only user-facing error messages without exposing internal service details

Platform Deployment Options

The BGBlur MCP server can be deployed on various cloud platforms. Each platform offers different scaling, pricing, and networking capabilities.

Config

# Railway
railway login
railway init
railway up
# Set BGBLUR_API_KEY in Railway dashboard

# Render
# Create render.yaml in repository
services:
  - type: web
    name: bgblur-mcp
    env: node
    buildCommand: npm install && npm run build
    startCommand: npm run dev:http
    envVars:
      - key: BGBLUR_API_KEY
        sync: false

# Fly.io
fly launch
fly secrets set BGBLUR_API_KEY=vba_your_api_key
fly deploy

# Google Cloud Run
gcloud run deploy bgblur-mcp \
  --source . \
  --set-env-vars BGBLUR_API_KEY=vba_your_api_key \
  --platform managed

Example Usage - Claude Desktop

Once configured, you can ask Claude to process images and videos using natural language. The AI agent will automatically call the appropriate BGBlur tools based on your request.

Config

# Example Prompts

"Blur the background in profile.jpg and save as profile-blurred.jpg"

"Remove the background from product-photo.png with transparency"

"Blur all faces in the video meeting-recording.mp4 for privacy"

"Detect and blur license plates in dashcam-footage.mp4"

"Check if image.jpg contains NSFW content before publishing"

"What's my current credit balance on BGBlur?"

# Claude will:
# 1. Select the appropriate tool (e.g., blur_background_image)
# 2. Upload your local file to BGBlur API
# 3. Monitor job status if processing is async
# 4. Download and save the processed result
# 5. Confirm completion with file path

Monitoring and Debugging

The BGBlur MCP server provides comprehensive logging and error handling to help diagnose issues during development and production.

Config

# Environment Variables for Debugging
NODE_ENV=development
LOG_LEVEL=debug
ALLOWED_HOSTS=localhost,127.0.0.1

# Log Locations
# Claude Desktop: Check Claude application logs
# Local Server: Console output with timestamps
# Docker: docker logs <container_id>

# Common Issues and Solutions
# - "401 Unauthorized": Check API key validity
# - "429 Rate Limited": Upgrade plan or reduce requests
# - "Insufficient credits": Purchase credits at /pricing
# - "File not found": Verify file path and permissions
# - Connection timeout: Check network and firewall settings

Resources & Support

Additional resources to help you get the most out of BGBlur MCP integration.

GitHub Repository

Source code and examples

API Documentation

REST API reference

Developer Dashboard

Manage API keys and usage

View Pricing & Credits Account Settings