Metadata-Version: 2.4
Name: autoreader-gmail-mcp
Version: 0.1.0
Summary: Production-grade multi-user Model Context Protocol (MCP) server for Gmail automation
Author: AutoReader Team
License-Expression: MIT
Keywords: mcp,gmail,ai,llm,automation,agent
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Communications :: Email
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.2.0
Requires-Dist: google-api-python-client>=2.118.0
Requires-Dist: google-auth-httplib2>=0.2.0
Requires-Dist: google-auth-oauthlib>=1.2.0
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: starlette>=0.27.0
Requires-Dist: uvicorn>=0.30.0
Requires-Dist: pydantic>=2.0.0
Dynamic: license-file

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