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.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues