Gmail AutoAuth by raghavared
raghavaredLABSCO SUMMARY
Inbox maintenance, not just inbox reading.
Most Gmail connectors stop at search and send. This one covers labels, filters and batch archiving, which is where the actual work of keeping a mailbox usable lives — and it does it against your own OAuth credentials rather than a third-party relay.
What it is
A Gmail connector covering the parts of the mailbox people actually maintain: not just reading and sending, but labels, folders, filters and the archive — the machinery that keeps an inbox from becoming a pile.
What you get
- Email — send with your own subject, content and recipients, read messages with full metadata, move to trash with confirmation, mark read or unread, open a message in the browser
- Drafts — create one for later review, list all drafts, edit an existing one
- Labels — list, create, apply and remove, rename, delete, and search by label
- Folders — create them (as Gmail labels), move email between them, list what exists
- Search and filters — Gmail's own advanced query syntax, plus creating, managing and deleting filters by sender, recipient, subject or content
- Archive — archive a message, batch-archive everything matching a search, list what is archived, and restore it to the inbox
Requirements
Python 3.12 or later (pyproject.toml requires it; the README still says 3.8+), uv, and a Google Cloud project with the Gmail API enabled. Configure the OAuth consent screen as External, add your own address as a test user, and add the https://www.googleapis.com/auth/gmail/modify scope; then create OAuth 2.0 credentials of type Desktop app and download the JSON. Keep it somewhere deliberate — the README's own suggestion is a ~/.gmail-mcp directory — and pass --creds-file-path and --token-path in the client config. Tokens refresh automatically once granted. The server asks for confirmation before sensitive actions, and the credential and token files should never reach version control.
Setup effort
Build from source — git clone https://github.com/theposch/gmail-mcp.git
USE CASES
01
Clearing out a newsletter backlog
Search for the sender and batch-archive everything that matches, rather than selecting pages of messages by hand.
02
Setting up filing that keeps working
Create a filter so future mail from a team is labelled automatically, instead of sorting it again next week.
03
Drafting a reply you want to check first
Have the draft written into Gmail so you review and send it yourself.
04
Finding something with Gmail's own syntax
Search using the advanced query language — sender, attachments, date — and get the matching messages with metadata.
05
Building a label structure
Create the labels you want, apply them to matching mail, and rename or remove the ones that stopped being useful.
06
Getting something back you archived
List what is in the archive and restore the message to the inbox.
BEFORE YOU INSTALL
What to know first
Requires
- uv on PATH
- Python 3.12+ (pyproject.toml; the README says 3.8+)
- A Google Cloud project with the Gmail API enabled
Where it runs
The documented client runs the server on your machine.
INSTALLATION
Connect your client
Server setup
TERMINAL
git clone https://github.com/theposch/gmail-mcp.git
cd gmail-mcp
python -m venv .venv
source .venv/bin/activateOn Windows: .venv\Scripts\activate.
TERMINAL
pip install -e .In Google Cloud: create a project, enable the Gmail API, configure the OAuth consent screen (External, add your email as a test user, add the scope https://www.googleapis.com/auth/gmail/modify), then create OAuth 2.0 credentials of type "Desktop app" and download the JSON file
TERMINAL
mkdir -p ~/.gmail-mcp && mv ~/Downloads/client_secret_*.json ~/.gmail-mcp/credentials.jsonMCP Clients
Claude Desktop
CLAUDE DESKTOP · JSON
{
"mcpServers": {
"gmail": {
"command": "uv",
"args": [
"--directory",
"<YOUR_PATH_TO_GMAIL_MCP>",
"run",
"gmail",
"--creds-file-path",
"<YOUR_PATH_TO_CREDENTIALS>",
"--token-path",
"<YOUR_PATH_TO_TOKENS>"
]
}
}
}<YOUR_PATH_TO_GMAIL_MCP> is your clone, and <YOUR_PATH_TO_CREDENTIALS> is the credentials file you downloaded from Google Cloud (e.g. ~/.gmail-mcp/credentials.json, written out in full), and <YOUR_PATH_TO_TOKENS> is where the server should keep its tokens.
