autoreader-gmail-mcp 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- autoreader_gmail_mcp-0.1.0/LICENSE +21 -0
- autoreader_gmail_mcp-0.1.0/PKG-INFO +87 -0
- autoreader_gmail_mcp-0.1.0/README.md +64 -0
- autoreader_gmail_mcp-0.1.0/auth.py +203 -0
- autoreader_gmail_mcp-0.1.0/autoreader_gmail_mcp.egg-info/PKG-INFO +87 -0
- autoreader_gmail_mcp-0.1.0/autoreader_gmail_mcp.egg-info/SOURCES.txt +13 -0
- autoreader_gmail_mcp-0.1.0/autoreader_gmail_mcp.egg-info/dependency_links.txt +1 -0
- autoreader_gmail_mcp-0.1.0/autoreader_gmail_mcp.egg-info/entry_points.txt +3 -0
- autoreader_gmail_mcp-0.1.0/autoreader_gmail_mcp.egg-info/requires.txt +8 -0
- autoreader_gmail_mcp-0.1.0/autoreader_gmail_mcp.egg-info/top_level.txt +4 -0
- autoreader_gmail_mcp-0.1.0/gmail_service.py +504 -0
- autoreader_gmail_mcp-0.1.0/pyproject.toml +37 -0
- autoreader_gmail_mcp-0.1.0/server.py +441 -0
- autoreader_gmail_mcp-0.1.0/setup.cfg +4 -0
- autoreader_gmail_mcp-0.1.0/web_app.py +1125 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 AutoReader
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: autoreader-gmail-mcp
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Production-grade multi-user Model Context Protocol (MCP) server for Gmail automation
|
|
5
|
+
Author: AutoReader Team
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Keywords: mcp,gmail,ai,llm,automation,agent
|
|
8
|
+
Classifier: Programming Language :: Python :: 3
|
|
9
|
+
Classifier: Operating System :: OS Independent
|
|
10
|
+
Classifier: Topic :: Communications :: Email
|
|
11
|
+
Requires-Python: >=3.10
|
|
12
|
+
Description-Content-Type: text/markdown
|
|
13
|
+
License-File: LICENSE
|
|
14
|
+
Requires-Dist: mcp>=1.2.0
|
|
15
|
+
Requires-Dist: google-api-python-client>=2.118.0
|
|
16
|
+
Requires-Dist: google-auth-httplib2>=0.2.0
|
|
17
|
+
Requires-Dist: google-auth-oauthlib>=1.2.0
|
|
18
|
+
Requires-Dist: python-dotenv>=1.0.1
|
|
19
|
+
Requires-Dist: starlette>=0.27.0
|
|
20
|
+
Requires-Dist: uvicorn>=0.30.0
|
|
21
|
+
Requires-Dist: pydantic>=2.0.0
|
|
22
|
+
Dynamic: license-file
|
|
23
|
+
|
|
24
|
+
# Gmail MCP Server
|
|
25
|
+
|
|
26
|
+
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.
|
|
27
|
+
|
|
28
|
+
---
|
|
29
|
+
|
|
30
|
+
## 📁 Project Structure
|
|
31
|
+
|
|
32
|
+
```
|
|
33
|
+
gmail-mcp-server/
|
|
34
|
+
│
|
|
35
|
+
├── server.py # 20 FastMCP Tools exposed for AI models / agents
|
|
36
|
+
├── auth.py # Google OAuth 2.0 authentication & automatic token refresh
|
|
37
|
+
├── gmail_service.py # Gmail API integration (threads, attachments, drafts, labels)
|
|
38
|
+
│
|
|
39
|
+
├── credentials.json # Google OAuth client secrets (configured)
|
|
40
|
+
├── token.json # Generated automatically after login
|
|
41
|
+
│
|
|
42
|
+
├── web_app.py # Web dashboard & interactive MCP playground
|
|
43
|
+
├── requirements.txt # Dependencies (mcp, google-api-client, etc.)
|
|
44
|
+
├── .env # Configuration file (custom paths, port)
|
|
45
|
+
└── README.md # Documentation
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
---
|
|
49
|
+
|
|
50
|
+
## 🧰 All 20 Registered MCP Tools
|
|
51
|
+
|
|
52
|
+
### 1. 📖 Reading & Analysis
|
|
53
|
+
* **`get_user_profile`**: Returns connected Gmail address and total message statistics.
|
|
54
|
+
* **`list_unread_emails(max_results)`**: Lists recent unread emails from the inbox with sender, subject, date, and snippet.
|
|
55
|
+
* **`search_emails(query, max_results)`**: Searches emails with standard Gmail filters (`from:`, `to:`, `subject:`, `after:`, `has:attachment`).
|
|
56
|
+
* **`get_email(message_id)`**: Fetches complete email details, decoded plain-text/HTML body, and **attachment metadata** (filenames, mime types, sizes).
|
|
57
|
+
* **`get_thread(thread_id)`**: Retrieves entire conversation threads in chronological order for complete back-and-forth context.
|
|
58
|
+
|
|
59
|
+
### 2. ✉️ Drafting & Sending
|
|
60
|
+
* **`send_email(to, subject, body, cc, bcc)`**: Immediately sends an email from the user's account.
|
|
61
|
+
* **`reply_email(message_id, body, reply_all)`**: Sends a reply preserving thread context, `In-Reply-To`, and `References` headers.
|
|
62
|
+
* **`create_draft(to, subject, body, cc, bcc)`**: Creates a draft email in Gmail without sending.
|
|
63
|
+
* **`list_drafts(max_results)`**: Lists all pending drafts in the mailbox.
|
|
64
|
+
* **`get_draft(draft_id)`**: Reads the full content of a draft.
|
|
65
|
+
* **`send_draft(draft_id)`**: Sends an existing draft after review.
|
|
66
|
+
* **`delete_draft(draft_id)`**: Discards an unwanted draft.
|
|
67
|
+
|
|
68
|
+
### 3. 🗂️ Organization & Management
|
|
69
|
+
* **`archive_email(message_id)`**: Archives an email (removes from Inbox, keeps safely in All Mail).
|
|
70
|
+
* **`mark_as_read(message_id)`**: Removes the `UNREAD` label.
|
|
71
|
+
* **`mark_as_unread(message_id)`**: Adds the `UNREAD` label.
|
|
72
|
+
* **`trash_email(message_id)`**: Moves an email to Trash.
|
|
73
|
+
* **`list_labels()`**: Lists all system labels and user custom folders.
|
|
74
|
+
* **`apply_label(message_id, label_name)`**: Tags an email (e.g. `Urgent`, `Invoices`, `Work`). Creates the label automatically if missing.
|
|
75
|
+
* **`remove_label(message_id, label_name)`**: Removes a label from an email.
|
|
76
|
+
* **`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).
|
|
77
|
+
|
|
78
|
+
---
|
|
79
|
+
|
|
80
|
+
## 🚀 Running the Server & Frontend
|
|
81
|
+
|
|
82
|
+
### Start the Interactive Frontend & Tools Playground
|
|
83
|
+
```bash
|
|
84
|
+
cd /home/thirunagarisrimehar/Desktop/3_months_plan/Auto_reader/gmail-mcp-server
|
|
85
|
+
./venv/bin/python web_app.py
|
|
86
|
+
```
|
|
87
|
+
Open **[http://localhost:5000](http://localhost:5000)** in your browser.
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
# Gmail MCP Server
|
|
2
|
+
|
|
3
|
+
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.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## 📁 Project Structure
|
|
8
|
+
|
|
9
|
+
```
|
|
10
|
+
gmail-mcp-server/
|
|
11
|
+
│
|
|
12
|
+
├── server.py # 20 FastMCP Tools exposed for AI models / agents
|
|
13
|
+
├── auth.py # Google OAuth 2.0 authentication & automatic token refresh
|
|
14
|
+
├── gmail_service.py # Gmail API integration (threads, attachments, drafts, labels)
|
|
15
|
+
│
|
|
16
|
+
├── credentials.json # Google OAuth client secrets (configured)
|
|
17
|
+
├── token.json # Generated automatically after login
|
|
18
|
+
│
|
|
19
|
+
├── web_app.py # Web dashboard & interactive MCP playground
|
|
20
|
+
├── requirements.txt # Dependencies (mcp, google-api-client, etc.)
|
|
21
|
+
├── .env # Configuration file (custom paths, port)
|
|
22
|
+
└── README.md # Documentation
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
---
|
|
26
|
+
|
|
27
|
+
## 🧰 All 20 Registered MCP Tools
|
|
28
|
+
|
|
29
|
+
### 1. 📖 Reading & Analysis
|
|
30
|
+
* **`get_user_profile`**: Returns connected Gmail address and total message statistics.
|
|
31
|
+
* **`list_unread_emails(max_results)`**: Lists recent unread emails from the inbox with sender, subject, date, and snippet.
|
|
32
|
+
* **`search_emails(query, max_results)`**: Searches emails with standard Gmail filters (`from:`, `to:`, `subject:`, `after:`, `has:attachment`).
|
|
33
|
+
* **`get_email(message_id)`**: Fetches complete email details, decoded plain-text/HTML body, and **attachment metadata** (filenames, mime types, sizes).
|
|
34
|
+
* **`get_thread(thread_id)`**: Retrieves entire conversation threads in chronological order for complete back-and-forth context.
|
|
35
|
+
|
|
36
|
+
### 2. ✉️ Drafting & Sending
|
|
37
|
+
* **`send_email(to, subject, body, cc, bcc)`**: Immediately sends an email from the user's account.
|
|
38
|
+
* **`reply_email(message_id, body, reply_all)`**: Sends a reply preserving thread context, `In-Reply-To`, and `References` headers.
|
|
39
|
+
* **`create_draft(to, subject, body, cc, bcc)`**: Creates a draft email in Gmail without sending.
|
|
40
|
+
* **`list_drafts(max_results)`**: Lists all pending drafts in the mailbox.
|
|
41
|
+
* **`get_draft(draft_id)`**: Reads the full content of a draft.
|
|
42
|
+
* **`send_draft(draft_id)`**: Sends an existing draft after review.
|
|
43
|
+
* **`delete_draft(draft_id)`**: Discards an unwanted draft.
|
|
44
|
+
|
|
45
|
+
### 3. 🗂️ Organization & Management
|
|
46
|
+
* **`archive_email(message_id)`**: Archives an email (removes from Inbox, keeps safely in All Mail).
|
|
47
|
+
* **`mark_as_read(message_id)`**: Removes the `UNREAD` label.
|
|
48
|
+
* **`mark_as_unread(message_id)`**: Adds the `UNREAD` label.
|
|
49
|
+
* **`trash_email(message_id)`**: Moves an email to Trash.
|
|
50
|
+
* **`list_labels()`**: Lists all system labels and user custom folders.
|
|
51
|
+
* **`apply_label(message_id, label_name)`**: Tags an email (e.g. `Urgent`, `Invoices`, `Work`). Creates the label automatically if missing.
|
|
52
|
+
* **`remove_label(message_id, label_name)`**: Removes a label from an email.
|
|
53
|
+
* **`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).
|
|
54
|
+
|
|
55
|
+
---
|
|
56
|
+
|
|
57
|
+
## 🚀 Running the Server & Frontend
|
|
58
|
+
|
|
59
|
+
### Start the Interactive Frontend & Tools Playground
|
|
60
|
+
```bash
|
|
61
|
+
cd /home/thirunagarisrimehar/Desktop/3_months_plan/Auto_reader/gmail-mcp-server
|
|
62
|
+
./venv/bin/python web_app.py
|
|
63
|
+
```
|
|
64
|
+
Open **[http://localhost:5000](http://localhost:5000)** in your browser.
|
|
@@ -0,0 +1,203 @@
|
|
|
1
|
+
import os
|
|
2
|
+
import sys
|
|
3
|
+
import re
|
|
4
|
+
import json
|
|
5
|
+
from pathlib import Path
|
|
6
|
+
from typing import List, Dict, Any, Optional
|
|
7
|
+
from dotenv import load_dotenv
|
|
8
|
+
from google.auth.transport.requests import Request
|
|
9
|
+
from google.oauth2.credentials import Credentials
|
|
10
|
+
from google_auth_oauthlib.flow import InstalledAppFlow, Flow
|
|
11
|
+
|
|
12
|
+
# Allow OAuth over HTTP for localhost development
|
|
13
|
+
os.environ["OAUTHLIB_INSECURE_TRANSPORT"] = "1"
|
|
14
|
+
|
|
15
|
+
# Base directory for the MCP server
|
|
16
|
+
BASE_DIR = Path(__file__).resolve().parent
|
|
17
|
+
if str(BASE_DIR) not in sys.path:
|
|
18
|
+
sys.path.insert(0, str(BASE_DIR))
|
|
19
|
+
|
|
20
|
+
# Load environment variables
|
|
21
|
+
load_dotenv(BASE_DIR / ".env")
|
|
22
|
+
|
|
23
|
+
# Directory for storing individual user tokens
|
|
24
|
+
TOKENS_DIR = BASE_DIR / "tokens"
|
|
25
|
+
TOKENS_DIR.mkdir(parents=True, exist_ok=True)
|
|
26
|
+
|
|
27
|
+
# Gmail API Scopes needed for reading, drafting, sending, and modifying labels
|
|
28
|
+
SCOPES = [
|
|
29
|
+
"https://www.googleapis.com/auth/gmail.readonly",
|
|
30
|
+
"https://www.googleapis.com/auth/gmail.send",
|
|
31
|
+
"https://www.googleapis.com/auth/gmail.compose",
|
|
32
|
+
"https://www.googleapis.com/auth/gmail.modify",
|
|
33
|
+
"https://www.googleapis.com/auth/userinfo.email",
|
|
34
|
+
"openid",
|
|
35
|
+
]
|
|
36
|
+
|
|
37
|
+
def get_credentials_path() -> Path:
|
|
38
|
+
"""Resolve path to credentials.json."""
|
|
39
|
+
custom_path = os.getenv("GMAIL_CREDENTIALS_PATH", "credentials.json")
|
|
40
|
+
path = Path(custom_path)
|
|
41
|
+
if not path.is_absolute():
|
|
42
|
+
path = BASE_DIR / path
|
|
43
|
+
return path
|
|
44
|
+
|
|
45
|
+
def _sanitize_user_id(user_id: str) -> str:
|
|
46
|
+
"""Sanitize user ID or email for safe file storage."""
|
|
47
|
+
return re.sub(r"[^a-zA-Z0-9_\-\.@]", "_", user_id)
|
|
48
|
+
|
|
49
|
+
def get_user_token_path(user_id: str) -> Path:
|
|
50
|
+
"""Get the token file path for a specific user."""
|
|
51
|
+
safe_name = _sanitize_user_id(user_id)
|
|
52
|
+
return TOKENS_DIR / f"{safe_name}.json"
|
|
53
|
+
|
|
54
|
+
def get_default_token_path() -> Path:
|
|
55
|
+
"""Legacy/default single-user token path."""
|
|
56
|
+
custom_path = os.getenv("GMAIL_TOKEN_PATH", "token.json")
|
|
57
|
+
path = Path(custom_path)
|
|
58
|
+
if not path.is_absolute():
|
|
59
|
+
path = BASE_DIR / path
|
|
60
|
+
return path
|
|
61
|
+
|
|
62
|
+
def list_authenticated_users() -> List[Dict[str, Any]]:
|
|
63
|
+
"""
|
|
64
|
+
List all users who have connected their Google account.
|
|
65
|
+
Returns a list of dicts with email, token_path, and validity status.
|
|
66
|
+
"""
|
|
67
|
+
users = []
|
|
68
|
+
|
|
69
|
+
# 1. Check tokens directory
|
|
70
|
+
if TOKENS_DIR.exists():
|
|
71
|
+
for token_file in TOKENS_DIR.glob("*.json"):
|
|
72
|
+
try:
|
|
73
|
+
with open(token_file, "r", encoding="utf-8") as f:
|
|
74
|
+
data = json.load(f)
|
|
75
|
+
email = data.get("account") or token_file.stem
|
|
76
|
+
users.append({
|
|
77
|
+
"user_id": token_file.stem,
|
|
78
|
+
"email": email,
|
|
79
|
+
"token_file": str(token_file),
|
|
80
|
+
"is_default": False
|
|
81
|
+
})
|
|
82
|
+
except Exception:
|
|
83
|
+
continue
|
|
84
|
+
|
|
85
|
+
# 2. Check legacy default token.json only if no users in tokens/ directory
|
|
86
|
+
legacy_path = get_default_token_path()
|
|
87
|
+
if legacy_path.exists() and not users:
|
|
88
|
+
try:
|
|
89
|
+
with open(legacy_path, "r", encoding="utf-8") as f:
|
|
90
|
+
data = json.load(f)
|
|
91
|
+
email = data.get("account") or "default_user"
|
|
92
|
+
users.append({
|
|
93
|
+
"user_id": "default",
|
|
94
|
+
"email": email,
|
|
95
|
+
"token_file": str(legacy_path),
|
|
96
|
+
"is_default": True
|
|
97
|
+
})
|
|
98
|
+
except Exception:
|
|
99
|
+
pass
|
|
100
|
+
|
|
101
|
+
return users
|
|
102
|
+
|
|
103
|
+
def save_user_credentials(user_id: str, creds: Credentials, email: Optional[str] = None) -> Path:
|
|
104
|
+
"""Save credentials for a specific user ID/email."""
|
|
105
|
+
token_path = get_user_token_path(user_id)
|
|
106
|
+
token_data = json.loads(creds.to_json())
|
|
107
|
+
if email:
|
|
108
|
+
token_data["account"] = email
|
|
109
|
+
|
|
110
|
+
with open(token_path, "w", encoding="utf-8") as f:
|
|
111
|
+
json.dump(token_data, f, indent=2)
|
|
112
|
+
|
|
113
|
+
# Also sync to default token.json if this is the only or primary user
|
|
114
|
+
default_path = get_default_token_path()
|
|
115
|
+
with open(default_path, "w", encoding="utf-8") as f:
|
|
116
|
+
json.dump(token_data, f, indent=2)
|
|
117
|
+
|
|
118
|
+
return token_path
|
|
119
|
+
|
|
120
|
+
def get_user_credentials(user_id: Optional[str] = None) -> Credentials:
|
|
121
|
+
"""
|
|
122
|
+
Retrieve and refresh credentials for a specific user.
|
|
123
|
+
If user_id is None, uses the first available authenticated user or default token.
|
|
124
|
+
"""
|
|
125
|
+
token_path = None
|
|
126
|
+
|
|
127
|
+
if user_id:
|
|
128
|
+
# Check specific user token path
|
|
129
|
+
candidate = get_user_token_path(user_id)
|
|
130
|
+
if candidate.exists():
|
|
131
|
+
token_path = candidate
|
|
132
|
+
else:
|
|
133
|
+
# Check by matching email in listed users
|
|
134
|
+
for u in list_authenticated_users():
|
|
135
|
+
if u["email"].lower() == user_id.lower() or u["user_id"] == user_id:
|
|
136
|
+
token_path = Path(u["token_file"])
|
|
137
|
+
break
|
|
138
|
+
|
|
139
|
+
# Fallback to default if no user_id specified or specific user not found
|
|
140
|
+
if not token_path or not token_path.exists():
|
|
141
|
+
default_path = get_default_token_path()
|
|
142
|
+
if default_path.exists():
|
|
143
|
+
token_path = default_path
|
|
144
|
+
else:
|
|
145
|
+
# Pick first available user in tokens directory
|
|
146
|
+
users = list_authenticated_users()
|
|
147
|
+
if users:
|
|
148
|
+
token_path = Path(users[0]["token_file"])
|
|
149
|
+
|
|
150
|
+
if not token_path or not token_path.exists():
|
|
151
|
+
raise FileNotFoundError(
|
|
152
|
+
f"No OAuth token found for user '{user_id or 'default'}'. "
|
|
153
|
+
"Please authenticate the user first."
|
|
154
|
+
)
|
|
155
|
+
|
|
156
|
+
creds = Credentials.from_authorized_user_file(str(token_path), SCOPES)
|
|
157
|
+
|
|
158
|
+
# Refresh if expired
|
|
159
|
+
if creds and creds.expired and creds.refresh_token:
|
|
160
|
+
try:
|
|
161
|
+
creds.refresh(Request())
|
|
162
|
+
# Save refreshed token
|
|
163
|
+
with open(token_path, "w", encoding="utf-8") as f:
|
|
164
|
+
f.write(creds.to_json())
|
|
165
|
+
except Exception as e:
|
|
166
|
+
print(f"[auth] Failed to refresh token for '{user_id}': {e}")
|
|
167
|
+
raise
|
|
168
|
+
|
|
169
|
+
return creds
|
|
170
|
+
|
|
171
|
+
def get_credentials() -> Credentials:
|
|
172
|
+
"""Backwards-compatible helper for single-user callers."""
|
|
173
|
+
return get_user_credentials(None)
|
|
174
|
+
|
|
175
|
+
def create_web_oauth_flow(redirect_uri: str) -> Flow:
|
|
176
|
+
"""
|
|
177
|
+
Create an OAuth flow for web-based multi-user authentication.
|
|
178
|
+
"""
|
|
179
|
+
credentials_path = get_credentials_path()
|
|
180
|
+
if not credentials_path.exists():
|
|
181
|
+
raise FileNotFoundError(f"credentials.json not found at: {credentials_path}")
|
|
182
|
+
|
|
183
|
+
return Flow.from_client_secrets_file(
|
|
184
|
+
str(credentials_path),
|
|
185
|
+
scopes=SCOPES,
|
|
186
|
+
redirect_uri=redirect_uri
|
|
187
|
+
)
|
|
188
|
+
|
|
189
|
+
def remove_user(user_id: str) -> bool:
|
|
190
|
+
"""Remove a user's stored OAuth token."""
|
|
191
|
+
path = get_user_token_path(user_id)
|
|
192
|
+
if path.exists():
|
|
193
|
+
path.unlink()
|
|
194
|
+
return True
|
|
195
|
+
return False
|
|
196
|
+
|
|
197
|
+
if __name__ == "__main__":
|
|
198
|
+
print(f"Base Directory: {BASE_DIR}")
|
|
199
|
+
print(f"Tokens Directory: {TOKENS_DIR}")
|
|
200
|
+
users = list_authenticated_users()
|
|
201
|
+
print(f"Authenticated Users ({len(users)}):")
|
|
202
|
+
for u in users:
|
|
203
|
+
print(f" - {u['email']} (File: {u['token_file']})")
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: autoreader-gmail-mcp
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Production-grade multi-user Model Context Protocol (MCP) server for Gmail automation
|
|
5
|
+
Author: AutoReader Team
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Keywords: mcp,gmail,ai,llm,automation,agent
|
|
8
|
+
Classifier: Programming Language :: Python :: 3
|
|
9
|
+
Classifier: Operating System :: OS Independent
|
|
10
|
+
Classifier: Topic :: Communications :: Email
|
|
11
|
+
Requires-Python: >=3.10
|
|
12
|
+
Description-Content-Type: text/markdown
|
|
13
|
+
License-File: LICENSE
|
|
14
|
+
Requires-Dist: mcp>=1.2.0
|
|
15
|
+
Requires-Dist: google-api-python-client>=2.118.0
|
|
16
|
+
Requires-Dist: google-auth-httplib2>=0.2.0
|
|
17
|
+
Requires-Dist: google-auth-oauthlib>=1.2.0
|
|
18
|
+
Requires-Dist: python-dotenv>=1.0.1
|
|
19
|
+
Requires-Dist: starlette>=0.27.0
|
|
20
|
+
Requires-Dist: uvicorn>=0.30.0
|
|
21
|
+
Requires-Dist: pydantic>=2.0.0
|
|
22
|
+
Dynamic: license-file
|
|
23
|
+
|
|
24
|
+
# Gmail MCP Server
|
|
25
|
+
|
|
26
|
+
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.
|
|
27
|
+
|
|
28
|
+
---
|
|
29
|
+
|
|
30
|
+
## 📁 Project Structure
|
|
31
|
+
|
|
32
|
+
```
|
|
33
|
+
gmail-mcp-server/
|
|
34
|
+
│
|
|
35
|
+
├── server.py # 20 FastMCP Tools exposed for AI models / agents
|
|
36
|
+
├── auth.py # Google OAuth 2.0 authentication & automatic token refresh
|
|
37
|
+
├── gmail_service.py # Gmail API integration (threads, attachments, drafts, labels)
|
|
38
|
+
│
|
|
39
|
+
├── credentials.json # Google OAuth client secrets (configured)
|
|
40
|
+
├── token.json # Generated automatically after login
|
|
41
|
+
│
|
|
42
|
+
├── web_app.py # Web dashboard & interactive MCP playground
|
|
43
|
+
├── requirements.txt # Dependencies (mcp, google-api-client, etc.)
|
|
44
|
+
├── .env # Configuration file (custom paths, port)
|
|
45
|
+
└── README.md # Documentation
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
---
|
|
49
|
+
|
|
50
|
+
## 🧰 All 20 Registered MCP Tools
|
|
51
|
+
|
|
52
|
+
### 1. 📖 Reading & Analysis
|
|
53
|
+
* **`get_user_profile`**: Returns connected Gmail address and total message statistics.
|
|
54
|
+
* **`list_unread_emails(max_results)`**: Lists recent unread emails from the inbox with sender, subject, date, and snippet.
|
|
55
|
+
* **`search_emails(query, max_results)`**: Searches emails with standard Gmail filters (`from:`, `to:`, `subject:`, `after:`, `has:attachment`).
|
|
56
|
+
* **`get_email(message_id)`**: Fetches complete email details, decoded plain-text/HTML body, and **attachment metadata** (filenames, mime types, sizes).
|
|
57
|
+
* **`get_thread(thread_id)`**: Retrieves entire conversation threads in chronological order for complete back-and-forth context.
|
|
58
|
+
|
|
59
|
+
### 2. ✉️ Drafting & Sending
|
|
60
|
+
* **`send_email(to, subject, body, cc, bcc)`**: Immediately sends an email from the user's account.
|
|
61
|
+
* **`reply_email(message_id, body, reply_all)`**: Sends a reply preserving thread context, `In-Reply-To`, and `References` headers.
|
|
62
|
+
* **`create_draft(to, subject, body, cc, bcc)`**: Creates a draft email in Gmail without sending.
|
|
63
|
+
* **`list_drafts(max_results)`**: Lists all pending drafts in the mailbox.
|
|
64
|
+
* **`get_draft(draft_id)`**: Reads the full content of a draft.
|
|
65
|
+
* **`send_draft(draft_id)`**: Sends an existing draft after review.
|
|
66
|
+
* **`delete_draft(draft_id)`**: Discards an unwanted draft.
|
|
67
|
+
|
|
68
|
+
### 3. 🗂️ Organization & Management
|
|
69
|
+
* **`archive_email(message_id)`**: Archives an email (removes from Inbox, keeps safely in All Mail).
|
|
70
|
+
* **`mark_as_read(message_id)`**: Removes the `UNREAD` label.
|
|
71
|
+
* **`mark_as_unread(message_id)`**: Adds the `UNREAD` label.
|
|
72
|
+
* **`trash_email(message_id)`**: Moves an email to Trash.
|
|
73
|
+
* **`list_labels()`**: Lists all system labels and user custom folders.
|
|
74
|
+
* **`apply_label(message_id, label_name)`**: Tags an email (e.g. `Urgent`, `Invoices`, `Work`). Creates the label automatically if missing.
|
|
75
|
+
* **`remove_label(message_id, label_name)`**: Removes a label from an email.
|
|
76
|
+
* **`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).
|
|
77
|
+
|
|
78
|
+
---
|
|
79
|
+
|
|
80
|
+
## 🚀 Running the Server & Frontend
|
|
81
|
+
|
|
82
|
+
### Start the Interactive Frontend & Tools Playground
|
|
83
|
+
```bash
|
|
84
|
+
cd /home/thirunagarisrimehar/Desktop/3_months_plan/Auto_reader/gmail-mcp-server
|
|
85
|
+
./venv/bin/python web_app.py
|
|
86
|
+
```
|
|
87
|
+
Open **[http://localhost:5000](http://localhost:5000)** in your browser.
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
LICENSE
|
|
2
|
+
README.md
|
|
3
|
+
auth.py
|
|
4
|
+
gmail_service.py
|
|
5
|
+
pyproject.toml
|
|
6
|
+
server.py
|
|
7
|
+
web_app.py
|
|
8
|
+
autoreader_gmail_mcp.egg-info/PKG-INFO
|
|
9
|
+
autoreader_gmail_mcp.egg-info/SOURCES.txt
|
|
10
|
+
autoreader_gmail_mcp.egg-info/dependency_links.txt
|
|
11
|
+
autoreader_gmail_mcp.egg-info/entry_points.txt
|
|
12
|
+
autoreader_gmail_mcp.egg-info/requires.txt
|
|
13
|
+
autoreader_gmail_mcp.egg-info/top_level.txt
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
|