# 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)

```bash
# 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

```bash
python -m vertex verify
```

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

### Start the server

```bash
# 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

```bash
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!**

```bash
./download_youtube.py
```

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

See [YOUTUBE_QUICK_START.md](YOUTUBE_QUICK_START.md) for usage guide.

---

## Email Cleanup Helper

Clean up newsletters, promotions, and mass emails safely:

```bash
# 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](EMAIL_CLEANUP_GUIDE.md) for detailed instructions.

---

## Running tests

```bash
# 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.