🚀 Google Gemini AI + YouTube MCP + Ngrok Gateway Engine

A zero-cost, persistent YouTube Studio Automation Engine powered by Google Gemini 2.5 Flash, a YouTube Studio Model Context Protocol (MCP) Server over Server-Sent Events (SSE) or Stdio, and an Ngrok HTTPS Gateway.

---

🌟 Key Features

• 🧠 AI-Powered Channel Creator Assistant: Uses Google Gemini (gemini-2.5-flash via @google/genai) to evaluate comment sentiment, craft engaging responses, and retrieve channel analytics.
• 📡 Model Context Protocol (MCP) Server: Exposes YouTube Studio capabilities (get_channel_stats, fetch_unanswered_comments, post_comment_reply) as standard MCP tools.
• 🌐 Ngrok Gateway: Programmatically establishes a secure public HTTPS tunnel to remote SSE/Webhook clients.
• 🔄 OAuth2 Persistent Connectivity: Automatically refreshes Google YouTube Data API access tokens seamlessly.
• ⏱️ Rate-Limit Resilience: Built-in exponential backoff retry logic handling HTTP 429 and rate-limiting gracefully.
• 🔌 Flexible Transports: Supports both Embedded Express SSE Mode out-of-the-box and External GitHub MCP Servers (via stdio).

---

📐 Architecture

graph TD
    A[Google Gemini API] <-->|Tool Declarations & Function Calls| B[Gemini Agent Orchestrator]
    B <-->|MCP Client Transport| C[Ngrok Gateway / HTTPS Tunnel]
    C <-->|SSE Transport /sse & /message| D[Express YouTube MCP Server]
    D <-->|OAuth2 Token Refresh & API Calls| E[YouTube Data API v3]

---

🛠️ Step-by-Step Prerequisites & Setup

1. Google Cloud OAuth2 Credentials

1. Go to the Google Cloud Console.
2. Create a new project or select an existing one.
3. Enable the YouTube Data API v3.
4. Go to APIs & Services > Credentials.
5. Click Create Credentials -> OAuth client ID.
6. Select Web application.
7. Under Authorized redirect URIs, add http://localhost:3000/oauth2callback.
8. Copy your Client ID and Client Secret.

---

2. Obtain YouTube OAuth Refresh Token

Run the included token setup wizard CLI to obtain your YOUTUBE_REFRESH_TOKEN:

1. Copy .env.example to .env and fill in your YOUTUBE_CLIENT_ID and YOUTUBE_CLIENT_SECRET:

   cp .env.example .env
   

2. Launch the OAuth helper wizard:

   npm run auth-helper
   

3. Open the generated authorization link in your browser, log in with your YouTube account, and accept the permissions.
4. The wizard will automatically output your YOUTUBE_REFRESH_TOKEN. Copy and paste it into .env.

---

3. Google Gemini API Key

1. Obtain a free API Key from Google AI Studio.
2. Add it to your .env file as GEMINI_API_KEY.

---

4. Ngrok Setup (Optional but Recommended)

1. Sign up for a free account at ngrok.com.
2. Copy your Auth Token from your Ngrok dashboard.
3. Set NGROK_AUTHTOKEN in your .env file.

---

⚙️ Environment Configuration (.env)

# Google Gemini API Key
GEMINI_API_KEY=your_gemini_api_key_here

# YouTube Data API v3 OAuth2 Credentials
YOUTUBE_CLIENT_ID=your_youtube_client_id_here
YOUTUBE_CLIENT_SECRET=your_youtube_client_secret_here
YOUTUBE_REFRESH_TOKEN=your_youtube_refresh_token_here

# Ngrok Auth Token
NGROK_AUTHTOKEN=your_ngrok_authtoken_here

# Server Configuration
PORT=3000

# MCP Connection Mode: "sse" (built-in express server) or "stdio" (external github mcp binary)
MCP_MODE=sse

# External GitHub MCP command configuration (only used if MCP_MODE=stdio)
EXTERNAL_MCP_COMMAND=npx
EXTERNAL_MCP_ARGS=-y,@pauling-ai/youtube-mcp-server

---

🚀 Running the Engine

Installation

npm install

Development Mode

npm run dev

Production Build & Launch

npm run build
npm start

---

🔌 Connecting External GitHub YouTube MCP Servers

If you want to use an external GitHub MCP Server (such as pauling-ai/youtube-mcp-server or a Python MCP binary):

1. Set MCP_MODE=stdio in your .env.
2. Configure EXTERNAL_MCP_COMMAND and EXTERNAL_MCP_ARGS to point to the executable:
   • For Node/NPM package:

     EXTERNAL_MCP_COMMAND=npx
     EXTERNAL_MCP_ARGS=-y,@pauling-ai/youtube-mcp-server
     

   • For Python MCP server:

     EXTERNAL_MCP_COMMAND=python
     EXTERNAL_MCP_ARGS=path/to/server.py
     

3. Run npm run dev to connect the Gemini Agent to the external MCP server process automatically.

---

📄 License

MIT