🤖 ModBuddy - AI-Powered YouTube Live Chat Moderator

An intelligent YouTube Live Chat moderator with MCP (Model Context Protocol) integration, Google AI, and real-time analytics.

🚀 Features

🎯 Real-time Chat Moderation - Automatically detect and remove toxic content
🤖 AI-Powered Responses - Smart FAQ handling with Google Gemini AI
📊 Live Analytics Dashboard - Real-time sentiment analysis and engagement metrics
🔌 MCP Protocol Integration - 13 advanced tools for external AI agents
⚡ High-Performance Architecture - Handles 120+ messages/minute with sub-3s response times
🛡️ Multi-layered Safety - Google AI + rule-based moderation systems

🚀 Quick Start

1. Install Dependencies

# Clone the repository
git clone https://github.com/yourusername/modbuddy.git
cd modbuddy

# Install Python dependencies
pip install -r requirements.txt

2. Set Up API Credentials

YouTube Data API v3:

Go to Google Cloud Console
Enable YouTube Data API v3
Create OAuth2 credentials
Download and save as config/credentials.json.template (rename to credentials.json)

Google AI (Gemini):

Visit Google AI Studio
Create API key
Add to .env file

Create .env file:

YOUTUBE_API_KEY=your_youtube_api_key
YOUTUBE_CLIENT_ID=your_client_id.apps.googleusercontent.com
YOUTUBE_CLIENT_SECRET=your_client_secret
GOOGLE_AI_API_KEY=your_gemini_api_key
YOUTUBE_VIDEO_ID=your_live_video_id
TOXICITY_THRESHOLD=0.7
MCP_SERVER_PORT=7860

3. Launch ModBuddy

Web Dashboard:

python run.py

Access at: http://localhost:7860

MCP Server (for Claude Desktop):

python mcp_fast_server.py

🔑 API Configuration

YouTube Data API v3

Purpose: Read/write YouTube Live Chat messages
Cost: Free tier (10,000 units/day ≈ 2,000 operations)
Setup:

Enable API in Google Cloud Console
Create OAuth2 credentials (not API key)
Configure authorized redirect URIs
Download client configuration JSON

Required OAuth2 credentials format (config/credentials.json):

{
  "installed": {
    "client_id": "your-client-id.apps.googleusercontent.com",
    "client_secret": "your-oauth2-client-secret", 
    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
    "token_uri": "https://oauth2.googleapis.com/token"
  }
}

Google AI (Gemini) API

Purpose: Intelligent question answering and content analysis
Cost: Free tier (60 requests/minute)
Setup: Simple API key from Google AI Studio

🔌 MCP Tools

ModBuddy exposes 5 standardized MCP tools for integration with AI agents:

`get_chat`

Fetch live chat messages with filtering options.

{
  "since_iso": "2024-01-15T10:30:00Z",
  "max_results": 50
}

`send_chat`

Send messages to the live chat as the bot.

{
  "text": "Welcome to the stream!"
}

`delete_msg`

Remove toxic or inappropriate messages.

{
  "message_id": "abc123xyz"
}

`moderate`

Analyze message toxicity and get moderation recommendations.

{
  "text": "Message content to analyze"
}

`get_live_insights`

Retrieve real-time analytics and engagement metrics.

{
  "window_minutes": 10
}

Access MCP tools at: http://localhost:7860/tools/list

🏗️ Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────────┐
│   AI Agents     │────│   MCP Protocol   │────│     ModBuddy       │
│ (Claude/GPT)    │    │    (5 tools)     │    │   Main Server      │
└─────────────────┘    └──────────────────┘    └─────────────────────┘
                                                           │
                                                           ▼
┌─────────────────────────────────────────────────────────────────────┐
│                        ModBuddy Core                                │
├─────────────────┬─────────────────┬─────────────────┬─────────────────┤
│  YouTube Client │   Google AI     │   Database      │  Web Dashboard  │
│  (OAuth2 + API) │   (Gemini)     │   (SQLite)      │   (Gradio)      │
└─────────────────┴─────────────────┴─────────────────┴─────────────────┘
                                    │
                                    ▼
                    ┌─────────────────────────────────┐
                    │       YouTube Live Chat         │
                    │     (Real-time messages)        │
                    └─────────────────────────────────┘

⚙️ Configuration Options

Environment Variables (.env)

Variable	Description	Default	Required
`YOUTUBE_API_KEY`	YouTube Data API v3 key	-	✅
`YOUTUBE_CLIENT_ID`	OAuth2 client ID	-	✅
`YOUTUBE_CLIENT_SECRET`	OAuth2 client secret	-	✅
`GOOGLE_AI_API_KEY`	Gemini AI API key	-	✅
`YOUTUBE_VIDEO_ID`	Live stream video ID	-	✅
`TOXICITY_THRESHOLD`	Moderation sensitivity (0.1-1.0)	0.7	❌
`CHAT_POLL_INTERVAL`	Message fetch interval (seconds)	5	❌
`MCP_SERVER_PORT`	Server port	7860	❌

Moderation Settings

Toxicity Threshold: 0.1 (very strict) to 1.0 (very permissive)
Auto-moderation: Automatically delete toxic messages
Auto-response: AI-generated responses to frequently asked questions
Custom Rules: Extend simple moderation with custom keywords

📊 Analytics & Monitoring

Real-time Dashboard Features

📈 Message Velocity - Messages per minute trending
😊 Sentiment Analysis - Positive/Neutral/Negative breakdown
👥 User Activity - Most active participants
🚨 Toxicity Timeline - Content safety over time
🌍 Language Detection - Multi-language chat support

Performance Metrics

Optimal Configuration:

Processes ~120 messages/minute
<3 second response time for AI answers
<2 second moderation decisions
Supports ~2,000 daily operations (YouTube quota)

🛠️ Troubleshooting

YouTube Authentication Issues

# Clear cached tokens and re-authenticate
rm config/token.json
python run.py

Common fixes:

Verify OAuth2 credentials in config/credentials.json
Check YouTube Data API v3 is enabled
Ensure video is currently live with chat enabled

Gemini AI Connection Problems

Verify API key at Google AI Studio
Check rate limits (60 requests/minute on free tier)
Monitor quota usage in API dashboard

MCP Tools Not Responding

# Test MCP endpoints directly
curl http://localhost:7860/tools/list

# Expected: JSON response with 5 tool definitions

Performance Optimization

High-traffic streams:

Increase CHAT_POLL_INTERVAL to reduce API calls
Lower TOXICITY_THRESHOLD for stricter moderation
Enable Redis caching for repeated questions

💻 Development

Project Structure

modbuddy/
├── src/
│   ├── main.py              # Gradio web server & MCP endpoints
│   ├── mcp_tools.py         # MCP tool implementations
│   ├── youtube_client.py    # YouTube Data API v3 wrapper
│   ├── google_ai.py         # Gemini AI integration
│   ├── simple_moderation.py # Rule-based content filtering
│   └── database.py          # SQLite data persistence
├── config/
│   └── credentials.json.template  # OAuth2 template
├── requirements.txt         # Python dependencies
├── run.py                  # Application launcher
└── README.md              # This file

Running Tests

# Test API connections
python -c "from src.youtube_client import YouTubeClient; YouTubeClient().test_connection()"

# Test Gemini AI
python -c "from src.google_ai import GoogleAIClient; GoogleAIClient().test_connection()"

Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit changes (git commit -m 'Add amazing feature')
Push to branch (git push origin feature/amazing-feature)
Open a Pull Request

🎯 Use Cases

Gaming Streamers

Auto-moderate toxic gaming chat
Handle stream commands and FAQs
Real-time sentiment monitoring during gameplay

Educational Content

Manage Q&A sessions automatically
Filter inappropriate content in learning environments
Track student engagement metrics

Product Launches

Remove spam during live demos
Gauge audience sentiment
Answer product questions intelligently

AI Developers

Integrate via MCP for custom automation
Build chat analytics pipelines
Create moderation workflows

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Support

Documentation: GitHub Wiki
Issues: GitHub Issues
Discussions: GitHub Discussions

⭐ Acknowledgments

Model Context Protocol (MCP) for standardized AI tool integration
Google AI for Gemini API and natural language processing
YouTube Data API v3 for live chat access
Gradio for rapid web interface development

Ready to moderate smarter? 🚀

⚡ Quick Start: pip install -r requirements.txt && python run.py
🔧 Configure APIs: Follow API Configuration
📊 View Dashboard: http://localhost:7860
🔌 MCP Tools: http://localhost:7860/tools/list

Name		Name	Last commit message	Last commit date
Latest commit History 12 Commits
config		config
src		src
.env.template		.env.template
.gitignore		.gitignore
README.md		README.md
mcp_fast_server.py		mcp_fast_server.py
requirements.txt		requirements.txt
run.py		run.py

yazmorukyaz/YouTube-Live-Stream-Moderator-MCP

Folders and files

Latest commit

History

Repository files navigation