Google MCP Server — AI agent for Gmail, Drive, Docs, YouTube & Calendar

This is an MCP (Model Context Protocol) server that lets an AI assistant read, search, and act on your Google Workspace account. It works with any MCP-compatible client (Claude, VS Code, Cursor, custom apps, etc.).

---

What it can do

Gmail

• Show your email address
• Read unread messages from your inbox
• Search emails by keyword, sender, date, etc.
• Get the full content of any email by ID
• List all your Gmail labels
• Send emails
• Bulk-modify messages matching a Gmail query (archive, mark read/unread, star, label, or trash)

Google Drive

• List files you have access to
• Search files by name
• Read text content of documents, spreadsheets, or files
• See file metadata (size, owner, dates)
• Browse recently modified files
• List what's inside a folder

Google Docs

• Read the full content of a document
• List your recent documents
• Get a summary (title, ID, revision, paragraph count)
• Search for specific text inside a document

YouTube

• Search for videos
• Get video details (views, likes, duration, description)
• List your subscriptions
• Get info on any channel
• Show your own channel stats
• List your playlists
• Download videos to local storage (mp4, webm, audio-only)
• List all videos from any channel (by URL, @username, or channel ID)
• Download entire channels (all videos from a channel to local disk)

Google Calendar

• List upcoming events
• Search events by keyword
• Show today's schedule
• Show this week's schedule
• List all your calendars
• Get event details by ID

---

Quick Start (one-time setup)

# 1. Run the setup script (installs everything automatically):
bash setup.sh

# 2. Activate the virtual environment:
source .venv/bin/activate

# 3. Run the interactive OAuth setup (opens a browser tab):
python -m vertex auth

What happens: A browser opens, you sign into Google, grant permissions, and credentials get saved to .env automatically.

Alternative: Manual credential setup

If you already have Google Cloud credentials:

1. Create an OAuth 2.0 Desktop Client ID at https://console.cloud.google.com/apis/credentials
2. Download the JSON and save it as client_secrets.json in the project root
3. Run python -m vertex auth
4. Or manually add to .env (see .env.example)

---

How to use it

Check your credentials work

python -m vertex verify

This tests connectivity to all 5 Google APIs. You'll see checkmarks or errors for each one.

Start the server

# Option A — using the module directly:
python -m vertex

# Option B — using the installed command:
google-mcp-server

The server starts and listens for MCP connections from your AI client.

Run the OAuth flow again

python -m vertex auth

Available CLI commands

Command	What it does
python -m vertex	Start the MCP server (default)
python -m vertex auth	Run the OAuth consent flow to get/renew a refresh token
python -m vertex verify	Check your credentials work with all Google APIs

---

YouTube Video & Live Stream Downloads

Simple downloader - just paste a YouTube link!

./download_youtube.py

Supports:

• ✅ Single video downloads (any quality)
• ✅ Live streams (current/ongoing)
• ✅ Past live streams
• ✅ Audio extraction (MP3)

See YOUTUBE_QUICK_START.md for usage guide.

---

Email Cleanup Helper

Clean up newsletters, promotions, and mass emails safely:

# See what can be cleaned up
python cleanup_emails.py stats

# Stage emails for review (adds _Review label)
python cleanup_emails.py stage

# Review what was labeled
python cleanup_emails.py review

# Delete confirmed emails
python cleanup_emails.py delete

See EMAIL_CLEANUP_GUIDE.md for detailed instructions.

---

Running tests

# Unit tests (no internet needed, ~15s):
python -m pytest tests/unit/ -q

# Integration tests (requires real Google credentials):
python -m pytest tests/integration/test_real_connection.py -v

# All tests:
python -m pytest tests/ -q

# Shell-based CLI tests:
bash tests/scripts/test_cli.sh

---

How it works

The server is built on the Model Context Protocol — a standard that lets AI tools communicate with external services. When an AI assistant calls a tool (like gmail_list_unread), the server:

1. Gets the right OAuth credentials for that service
2. Makes the Google API call
3. Returns the result as readable text
4. The AI reads it and can use it in its response or chain more calls

The server handles authentication automatically using saved refresh tokens — no need to re-authorize each time.