Skip to main content
Glama
Gmail Local Search

Gmail Local Search

by koenvaneijk

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%\GmailLocalMCP on 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)

  1. Visit https://console.cloud.google.com/ and select/create a project.

  2. In APIs & Services → Library, enable Gmail API.

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

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

  5. Under Data Access, request https://www.googleapis.com/auth/gmail.readonly if you are asked to configure scopes.

  6. 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 doctor

Later, 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 doctor

The 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-mcp location (e.g. gmail-local.exe is in Scripts\).

4. Build the index

.\.venv\Scripts\gmail-local.exe sync

The 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 10

For a deliberate full reconciliation:

.\.venv\Scripts\gmail-local.exe full

If 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.tray

Right-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 900

Don'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.exe

  • Arguments: -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.server

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

The link uses a Gmail search URL, such as:

https://mail.google.com/mail/u/0/#search/rfc822msgid%3Aexample-id%40example.com

Gmail'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 1

Then 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-mcp separately 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_HOME profiles 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…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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.
      18
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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 npm
      4
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Reads 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.
      3
      MIT