🧠 Brainrot MCP Server

An advanced Model Context Protocol (MCP) server that enables AI assistants (like Gemini/Antigravity) to automatically generate vertical "brainrot" style videos. It takes a text script, generates high-quality localized Text-to-Speech voiceovers with synchronized word-wrapped subtitles, overlays custom SVG graphics at precise timestamps, ducks background audio, and renders a complete MP4 ready for publishing.

🗺️ System Architecture

graph TD
    Client[AI Client / Gemini / Antigravity] -->|1. Call create_brainrot_video| MCP[Brainrot MCP Server]
    MCP -->|2. Generate Audio & Subtitles| TTS[Local Piper TTS Service]
    TTS -->|3. Audio WAV & SRT timings| MCP
    MCP -->|4. Convert SVGs to PNG| IM[ImageMagick / librsvg]
    MCP -->|5. Slice, Overlay, Duck & Render| MP[MoviePy Engine]
    MP -->|6. Save Video| Out[(Output Directory)]

Related MCP server: AITuber MCP Server

⚡ Quick Start (Automated Setup)

The easiest way to get everything up and running is using the automated setup script, which automatically registers the MCP server in your Gemini config and starts the Docker services.

1. Download Background Videos

Before running the setup, you must download at least one background video (e.g., Minecraft parkour, Subway Surfers gameplay, or satisfying sand-cutting videos in vertical aspect ratio) and place it in the videos directory.

• Directory: [project_root]/videos/

• Supported Formats: .mp4, .webm, .mov, .mkv, .avi

2. Run the Setup Script

Run the script appropriate for your operating system:

Windows (PowerShell / CMD)

.\scripts\setup.bat

Linux / macOS

chmod +x scripts/setup.sh
./scripts/setup.sh

🛠️ Manual Setup (Step-by-Step)

If you prefer to configure the server manually or do not want to use the setup script, follow these steps:

1. Prepare Background Footage

Download vertical background videos and place them into the videos/ folder inside the project root:

brainrot-mcp/
├── videos/
│   ├── minecraft_parkour.mp4
│   └── subway_surfers.mp4

2. Run with Docker Compose

From the project root directory, build and launch the multi-container setup in detached mode:

docker compose up --build -d

This launches two services:

• tts-service on port 8000: Runs the Piper TTS FastAPI server.

• mcp-server on port 8543: Runs the FastMCP server exposed over streamable-http at /mcp.

3. Register the MCP Server

Add the server entry to your client configuration file.

• Config Path: ~/.gemini/config/mcp_config.json (or config.json)

• JSON Block:

{
  "mcpServers": {
    "brainrot": {
      "serverUrl": "http://localhost:8543/mcp"
    }
  }
}

⚙️ How It Works Under the Hood

🎙️ Local Text-To-Speech Service (/tts)

• Core Engine: Powered by Piper TTS using the high-quality en_US-ryan-medium.onnx voice. It executes on the GPU (via CUDA) if a compatible Nvidia card is available, gracefully falling back to CPU execution.

• Text Sanitization: Includes a robust regular-expression pre-processor that translates spoken stumbling blocks into natural speech:

  • IP addresses: 127.0.0.1 ➡️ "one two seven dot zero dot zero dot one"

  • Domain names: google.com ➡️ "google dot com"

  • Acronyms/Protocols: HTTP, mcp, URL, localhost ➡️ "H T T P", "M C P", "U R L", "local host"

🎬 Video Composition Engine (/mcp_server)

• Dynamic Slicing: Loads a random background video from your videos/ folder and crops/loops it to perfectly match the duration of the generated speech audio.

• Vertical Layout Optimization: Resizes output footage to 540p width (540x960 vertical format, qHD) to guarantee lightning-fast render speeds while maintaining sharp resolution on mobile screens.

• Subtitle Synced Overlays: Parses SRT subtitles returned from the Piper engine. Wraps text block widths to prevent clipping and uses yellow text with thick black borders (TextClip) for maximum readability.

• SVG Graphics Renderer: Converts arbitrary inline SVGs supplied by the AI model into transparent PNGs using rsvg-convert or ImageMagick, then composites them on screen at specific script checkpoints.

• Audio Ducking: Automatically scales the background audio of the original video down to 8% volume, layering the clear TTS voiceover on top.

🔌 MCP Tool Reference

The server exposes a single, powerful tool to the AI model:

create_brainrot_video

Generates a vertical brainrot video with text-to-speech voiceover and synchronized subtitles.

Arguments

• script (string, required): The voiceover script. Supports inline tags:

  • [show_image <key>] ... [end_show_image]: Displays the image associated with <key> during the reading of this text segment.

  • [wait <float>s]: Pauses the voiceover generation for the specified duration (e.g. [wait 1.5s]).

• title (string, optional): The title of the video. It will appear centered as an intro card for 0.5s and then slide to the top-left corner as a constant watermark.

• images_json (string, optional): A JSON string mapping the image keys used in the script tags to raw SVG source strings.

Example Payload

{
  "title": "LOCALHOST DEMO",
  "script": "[show_image server_icon] Starting up the local host server at 127.0.0.1. [end_show_image] We are online! [wait 1.5s] Check it out.",
  "images_json": "{\"server_icon\": \"<svg width='100' height='100'><circle cx='50' cy='50' r='40' fill='green'/></svg>\"}"
}

🧪 Testing the Setup

You can run the included Python test client to verify that your Docker services are running and the MCP tool executes correctly.

1. Set Up Environment

Ensure you have the required dependencies installed (ideally in your virtual environment):

pip install fastmcp
# Or using uv:
uv pip install fastmcp

2. Run Test Client

Make sure the docker containers are running (docker compose ps), then run:

python test_client.py

This script will:

1. Connect to the MCP server at http://localhost:8543/mcp.

2. Retrieve and print available tools.

3. Call create_brainrot_video with a sample script containing wait states, inline SVG images, and a title.

4. Save the compiled video to the ./output/ folder.