Skip to main content
Glama
Gmail MCP Server

Gmail MCP Server

by Mehar123456
README.md
# Gmail MCP Server

A complete, production-grade Model Context Protocol (MCP) server that empowers an AI assistant to read, search, analyze conversation threads, draft, send, reply to, categorize, and batch-automate Gmail mailboxes.

---

## šŸ“ Project Structure

```
gmail-mcp-server/
│
ā”œā”€ā”€ server.py              # 20 FastMCP Tools exposed for AI models / agents
ā”œā”€ā”€ auth.py                # Google OAuth 2.0 authentication & automatic token refresh
ā”œā”€ā”€ gmail_service.py       # Gmail API integration (threads, attachments, drafts, labels)
│
ā”œā”€ā”€ credentials.json       # Google OAuth client secrets (configured)
ā”œā”€ā”€ token.json             # Generated automatically after login
│
ā”œā”€ā”€ web_app.py             # Web dashboard & interactive MCP playground
ā”œā”€ā”€ requirements.txt       # Dependencies (mcp, google-api-client, etc.)
ā”œā”€ā”€ .env                   # Configuration file (custom paths, port)
└── README.md              # Documentation
```

---

## 🧰 All 20 Registered MCP Tools

### 1. šŸ“– Reading & Analysis
* **`get_user_profile`**: Returns connected Gmail address and total message statistics.
* **`list_unread_emails(max_results)`**: Lists recent unread emails from the inbox with sender, subject, date, and snippet.
* **`search_emails(query, max_results)`**: Searches emails with standard Gmail filters (`from:`, `to:`, `subject:`, `after:`, `has:attachment`).
* **`get_email(message_id)`**: Fetches complete email details, decoded plain-text/HTML body, and **attachment metadata** (filenames, mime types, sizes).
* **`get_thread(thread_id)`**: Retrieves entire conversation threads in chronological order for complete back-and-forth context.

### 2. āœ‰ļø Drafting & Sending
* **`send_email(to, subject, body, cc, bcc)`**: Immediately sends an email from the user's account.
* **`reply_email(message_id, body, reply_all)`**: Sends a reply preserving thread context, `In-Reply-To`, and `References` headers.
* **`create_draft(to, subject, body, cc, bcc)`**: Creates a draft email in Gmail without sending.
* **`list_drafts(max_results)`**: Lists all pending drafts in the mailbox.
* **`get_draft(draft_id)`**: Reads the full content of a draft.
* **`send_draft(draft_id)`**: Sends an existing draft after review.
* **`delete_draft(draft_id)`**: Discards an unwanted draft.

### 3. šŸ—‚ļø Organization & Management
* **`archive_email(message_id)`**: Archives an email (removes from Inbox, keeps safely in All Mail).
* **`mark_as_read(message_id)`**: Removes the `UNREAD` label.
* **`mark_as_unread(message_id)`**: Adds the `UNREAD` label.
* **`trash_email(message_id)`**: Moves an email to Trash.
* **`list_labels()`**: Lists all system labels and user custom folders.
* **`apply_label(message_id, label_name)`**: Tags an email (e.g. `Urgent`, `Invoices`, `Work`). Creates the label automatically if missing.
* **`remove_label(message_id, label_name)`**: Removes a label from an email.
* **`batch_modify_emails(message_ids, add_labels, remove_labels)`**: Modifies labels on up to 1,000 emails in a single fast API call (for bulk mark-as-read, bulk archiving, or bulk labeling).

---

## šŸš€ Running the Server & Frontend

### Start the Interactive Frontend & Tools Playground
```bash
cd /home/thirunagarisrimehar/Desktop/3_months_plan/Auto_reader/gmail-mcp-server
./venv/bin/python web_app.py
```
Open **[http://localhost:5000](http://localhost:5000)** in your browser.