Bumi Digital MCP Server

Model Context Protocol (MCP) server for Bumi Digital — generate AI images, videos, audio, and upscale media directly from MCP-compatible AI assistants (Claude Desktop, ChatGPT, Cursor, Trae, and others).

This server is a thin wrapper over the Bumi Digital public REST API v1. All business logic (credits, refunds, storage, webhooks) is enforced by the API — nothing is duplicated here.

Features

• 11 tools covering the full Bumi Digital API surface
• Dual transport: stdio (local) and Streamable HTTP (remote/hosted)
• Per-request auth in HTTP mode — one deployment serves many users, each with their own API key
• Stateless HTTP — no session storage required, scales horizontally
• Docker-ready — Dockerfile included for Coolify/VPS deployment

Tools

Tool	Description
generate_image	Generate images (text-to-image, image-to-image)
generate_video	Generate videos (text-to-video, image-to-video, motion control, avatar, lipsync)
generate_audio	Generate audio (music, speech/TTS, lipsync)
upscale_image	Upscale images to higher resolution
upscale_video	Upscale videos to higher resolution
list_models	List available AI models by type
get_models_pricing	List models with credit pricing and full input schemas
check_credits	Check current credit balance
get_generation_status	Poll status/result of an async generation
list_generations	Generation history with filters and pagination
upload_file	Upload image/video/audio (via source_url or base64) for use as generation input

Generation endpoints may return status: "completed" immediately or "processing" for async results — poll with get_generation_status until completed/failed. Credits are deducted upfront and refunded automatically on failure.

Getting an API Key

1. Sign in to bumi.digital
2. Go to Settings → API Keys
3. Create a key — it starts with bd_

Usage

Option A: stdio (local MCP client)

Install instantly via npx — no cloning or building required. Add to your MCP client config (Claude Desktop, Cursor, Trae, etc.):

{
  "mcpServers": {
    "bumi-digital": {
      "command": "npx",
      "args": ["-y", "bumi-digital-mcp"],
      "env": { "BUMI_API_KEY": "bd_xxx" }
    }
  }
}

<details> <summary>Alternative: run from source</summary>

git clone https://github.com/ezmakeai/bumi-digital-mcp.git
cd bumi-digital-mcp
npm install
npm run build

{
  "mcpServers": {
    "bumi-digital": {
      "command": "node",
      "args": ["/path/to/bumi-digital-mcp/dist/index.js"],
      "env": { "BUMI_API_KEY": "bd_xxx" }
    }
  }
}

</details>

Option B: Remote MCP (hosted via HTTP)

Run the server:

node dist/index.js --http
# or: MCP_TRANSPORT=http node dist/index.js

Client config — no installation needed, just the URL:

{
  "mcpServers": {
    "bumi-digital": {
      "url": "https://mcp.bumi.digital/mcp",
      "headers": {
        "Authorization": "Bearer bd_your_api_key_here"
      }
    }
  }
}

Endpoints:

• POST /mcp — MCP protocol (Streamable HTTP)
• GET /health — health check, returns { "ok": true }

In HTTP mode the API key is resolved per request, in this priority order:

1. ?api_key=bd_... query parameter (for clients without custom headers, e.g. ChatGPT)
2. Authorization: Bearer bd_... header
3. BUMI_API_KEY environment variable (fallback)

Option C: ChatGPT connector (Developer Mode)

ChatGPT connectors do not support custom headers — only OAuth or no authentication. Pass your API key as a query parameter instead:

• Server URL: https://mcp.bumi.digital/mcp?api_key=bd_your_api_key_here
• Authentication: None (no OAuth)

The server reads api_key from the query string first, then falls back to the Authorization header.

Note: keys in URLs may appear in server/proxy logs. Prefer the Authorization header (Option B) when your client supports it.

Configuration

Environment Variable	Default	Description
BUMI_API_KEY	—	API key for stdio mode. In HTTP mode this is only a fallback — clients normally pass their own key via header or ?api_key=
BUMI_BASE_URL	https://bumi.digital	Bumi Digital API base URL. Set to http://localhost:3000 for local development
PORT	3100	HTTP listen port (HTTP mode only)
MCP_TRANSPORT	—	Set to http to force HTTP mode without the --http flag

Self-Hosting (Optional)

If you operate your own Bumi Digital instance, this server can be self-hosted in HTTP mode. A Dockerfile is included — it builds the project and serves /mcp on PORT (default 3100). Point your MCP clients to https://your-domain/mcp with Authorization: Bearer bd_....

Development

npm install
npm run build        # compile TypeScript
npm run start        # HTTP mode on PORT (default 3100)
npm run start:stdio  # stdio mode (local MCP clients)

Requires Node.js >= 18.

License

MIT