Gmail Local Search
Provides read-only Gmail integration by indexing Gmail messages into a local SQLite FTS5 search index. Supports searching mail by text, sender, date range, label, and account; retrieving messages; generating Gmail search links to open messages; checking index status; and syncing Gmail history incrementally.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Gmail Local MCP
A local read-only Gmail → SQLite FTS5 index, searchable from Goose Desktop or a Windows tray app. It works directly against Gmail (no Outlook required).
Stable handles:
gmail:<account>:<Gmail API message ID>; Gmail IDs survive archive/label changes.Web opening: search
rfc822msgid:<Message-ID>in Gmail; more reliable than using API thread IDs in Gmail UI URLs. Opens the matching search result (sometimes requires a click), not a guaranteed direct message page.Indexed: subject, from/to, text and HTML email body, snippet, labels, date, thread and RFC message IDs. Attachments not indexed. Bodies limited to 200,000 characters per message.
Sync: resumable 500-message listing, incremental Gmail
history.list, re-run full scan if the history cursor expires; stop if >30% of the account would disappear in one reconciliation.Local only: OAuth token and plaintext SQLite database live under
%LOCALAPPDATA%\GmailLocalMCPon Windows. The MCP never sends mail or modifies Gmail.Optional tray: full-text search, double-click opening Gmail, auto-sync every 15 minutes, optional Windows startup. The tray does not require Gmail browser to be open.
1. Prerequisites
Windows 10/11 and normal Python 3.11–3.13 recommended, with pip and Tkinter. Python 3.15 may work but is not tested with all dependencies.
An existing Gmail/Google account and a Google Cloud project. No app password and no IMAP needed.
Goose Desktop (if using the MCP).
Related MCP server: Gmail MCP Server
2. Set up Google OAuth (one-time, 5–10 steps)
Visit https://console.cloud.google.com/ and select/create a project.
In APIs & Services → Library, enable Gmail API.
In Google Auth Platform, preferably choose Personal mode for a project you will use only with your own Google Account, if available. Google states that Personal mode avoids app verification and short-lived 7-day testing refresh tokens. Personal mode cannot be shared with other people's Gmail accounts.
If Personal mode is unavailable, set up Branding/Audience and create an External app with your Google Account added as a test user; note that Testing OAuth refresh tokens typically expire after 7 days for Gmail scopes. For ongoing unattended sync, do not leave a shared/externally targeted project in Testing. Production apps using restricted Gmail scopes may need Google's verification/security review.
Under Data Access, request
https://www.googleapis.com/auth/gmail.readonlyif you are asked to configure scopes.Under Clients, create a Desktop app OAuth client. Download the JSON client file (e.g.
client_secret_....json). Keep it private and do not commit it to GitHub.
Official docs: Gmail Python quickstart · OAuth Personal mode · Gmail scopes.
3. Install & authenticate
Option A: install from GitHub with pip
Create a virtual environment and install the package directly from GitHub. In PowerShell:
py -3.13 -m venv $HOME\.venvs\gmail-local-mcp
$HOME\.venvs\gmail-local-mcp\Scripts\python.exe -m pip install "gmail-local-mcp[tray] @ git+https://github.com/koenvaneijk/gmail-local-mcp.git"
$HOME\.venvs\gmail-local-mcp\Scripts\gmail-local.exe auth --client "C:\Users\YOURNAME\Downloads\client_secret_....json"
$HOME\.venvs\gmail-local-mcp\Scripts\gmail-local.exe doctorLater, update with pip install --upgrade "gmail-local-mcp[tray] @ git+https://github.com/koenvaneijk/gmail-local-mcp.git".
Option B: clone the repository
Extract/clone into e.g. C:\Tools\gmail-local-mcp. In PowerShell:
cd C:\Tools\gmail-local-mcp
py -3.13 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[tray]"
.\.venv\Scripts\gmail-local.exe auth --client "C:\Users\YOURNAME\Downloads\client_secret_....json"
.\.venv\Scripts\gmail-local.exe doctorThe authorization command opens your regular browser so you can consent to read-only Gmail access. A local OAuth refresh token is saved to your Windows profile. Later syncs reuse it without logging in again (unless revoked or expired).
The remaining steps use
C:\Tools\gmail-local-mcp\.venv\Scripts\...paths from option B. If you used option A, replace the venv path with your$HOME\.venvs\gmail-local-mcplocation (e.g.gmail-local.exeis inScripts\).
4. Build the index
.\.venv\Scripts\gmail-local.exe syncThe first run scans the entire Gmail mailbox, including Spam and Trash. It may take hours or longer for a very large mailbox because it fetches message bodies through Google's API. Quota/rate limits and network outages affect duration. Stop with Ctrl+C and run the same command again to resume; page checkpoints are recorded. Full scans skip fetching bodies of messages already indexed.
Check it:
.\.venv\Scripts\gmail-local.exe status
.\.venv\Scripts\gmail-local.exe search "factuur 2025" --limit 10For a deliberate full reconciliation:
.\.venv\Scripts\gmail-local.exe fullIf you intentionally deleted more than 30% of indexed messages and a full scan is blocked by the safety limit, check the account/mailbox first, then explicitly run full --allow-large-deletions.
5. Keep in sync (choose ONE method)
Recommended on Windows: tray app
.\.venv\Scripts\pythonw.exe -m gmail_local_mcp.trayRight-click the Gmail tray icon to search, sync now, pause, and enable Start with Windows. Double-click search results to open Gmail.
Alternative: terminal-based worker
.\.venv\Scripts\gmail-local.exe watch --interval 900Don't run watch and the tray together. They use a cross-process sync lock; only one will run at a time. The tray stays running when the Gmail website is closed. Network/API errors are retried on the next cycle; tray errors are logged to %LOCALAPPDATA%\GmailLocalMCP\tray.log.
6. Configure Goose Desktop
Goose → Settings → Extensions → Add custom extension → STDIO.
Name: Gmail Local Search
Command:
C:\Tools\gmail-local-mcp\.venv\Scripts\python.exeArguments:
-m gmail_local_mcp.server
If Goose expects a single command field, enter:
C:\Tools\gmail-local-mcp\.venv\Scripts\python.exe -m gmail_local_mcp.serverRestart the extension after installation. Try:
Zoek e-mails over facturen van 2025 en geef de Gmail-links.
Open de eerste gevonden e-mail in Gmail.
MCP tools: search_mail, get_mail, open_mail_in_gmail, index_status.
Search supports normal AND matching, or syntax="fts" for SQLite FTS5 expressions, plus sender, after/before dates (YYYY-MM-DD, UTC), label ID, account, limit and offset. Message and account IDs are stable across Gmail label changes.
7. Important: Gmail links and multiple accounts
The link uses a Gmail search URL, such as:
https://mail.google.com/mail/u/0/#search/rfc822msgid%3Aexample-id%40example.comGmail's rfc822msgid: search operator is documented, but the browser hash URL format is not an official Gmail API contract. If Google changes the UI, it may need maintenance. Emails lacking the RFC Message-ID header use a less reliable thread-ID fallback.
Account selector: /u/0/ is the first Google account signed into your browser, not necessarily the same account authorized by this application. If you're signed into multiple accounts, set the correct account index before launching Goose and the tray:
setx GMAIL_WEB_ACCOUNT_INDEX 1Then restart Goose/tray (and PowerShell). The account index may change as browser accounts are added/removed. Don't use the undocumented /u/email@gmail.com/ path: Google has changed its behavior.
Security, reliability, and limitations
Scope is
gmail.readonly; no send/modify/delete operations are registered. Opening a Gmail URL launches your default local web browser.Mail bodies and OAuth tokens are sensitive plaintext on disk; use Windows BitLocker and standard user account protections. Never publish your local data folder or
token.json. Your email content remains accessible to any authorized local MCP client (Goose included), which may transmit retrieved content to your chosen model provider.Gmail's API can rate-limit long runs. An API history cursor typically remains available for at least one week but can expire sooner; a full re-listing then becomes necessary.
The initial index is not instantaneous and need not perfectly match Gmail until it completes and replays history changes.
Search matches message text but not attached PDFs/Word/Excel; use
local-docs-mcpseparately for local files.One OAuth account is supported per installation/profile. The database schema isolates accounts, but for multiple Gmail accounts use separate
GMAIL_LOCAL_HOMEprofiles and Goose MCP extensions.Fully deleted Gmail messages are removed on the next sync. Archive/label changes preserve their Gmail message IDs and corresponding local handles.
Running in a remote container instead of on your local Windows PC won't open Gmail on your own desktop when the MCP opener runs.
Updating the install
If you installed from GitHub with pip (section 3, option A), pull the latest version with:
pip install --upgrade "gmail-local-mcp[tray] @ git+https://github.com/koenvaneijk/gmail-local-mcp.git"If you cloned the repository instead, git pull and re-run pip install -e ".[tray]" inside the venv.
Credentials and personal mail belong in %LOCALAPPDATA%, not in Git. Review the .gitignore before publishing to a repository.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Manage Gmail end-to-end: search, read, send, draft, label, and organize threads. Automate workflow…
Search Gmail and Outlook, save drafts, manage email rules, and view email stats.
Read, search and draft email; nothing is sent until you confirm.
Connect Gmail, iCloud Mail, Outlook, Yahoo Mail, Fastmail and other IMAP inboxes to ChatGPT, Claude and compatible AI assistants. Find emails by meaning across languages with semantic search. Ask AI to find customer conversations, summarize deadlines and draft follow-ups. Give a sales rep access to a shared outreach inbox or bring email into a compatible CRM. Share an iCloud custom-domain inbox with teammates without their own Apple ID or iCloud+ plan. Search results may be incomplete or stale; separate permissions control mail actions.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables interaction with Gmail through the Gmail API to read, send, and manage emails. Supports multiple Gmail accounts with real-time monitoring and advanced features for email search and attachment handling.18Apache 2.0
- AlicenseAqualityDmaintenanceEnables natural language interaction with Gmail, providing email search, categorized daily summaries, and Home Assistant integration through REST API with read-only access to your inbox.20MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to query and recall your entire Gmail inbox locally, providing fast summarization and semantic search without relying on Gmail's search API.68 npm4MIT
- AlicenseAqualityCmaintenanceReads and searches local email archives (.mbox or .eml) with full MIME parsing, enabling queries about senders, subjects, dates, and bodies while keeping all data on your machine.3MIT