Skip to main content
Glama
Gmail Local Search

Gmail Local Search

by koenvaneijk
README.md
# 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).

## 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](https://developers.google.com/workspace/gmail/api/quickstart/python) · [OAuth Personal mode](https://support.google.com/cloud/answer/15544987?hl=en) · [Gmail scopes](https://developers.google.com/workspace/gmail/api/auth/scopes).

## 3. Install & authenticate

### Option A: install from GitHub with pip

Create a virtual environment and install the package directly from GitHub. In PowerShell:

```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:

```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

```powershell
.\.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:

```powershell
.\.venv\Scripts\gmail-local.exe status
.\.venv\Scripts\gmail-local.exe search "factuur 2025" --limit 10
```

For a deliberate full reconciliation:

```powershell
.\.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**

```powershell
.\.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**

```powershell
.\.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:

```text
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.

## 7. Important: Gmail links and multiple accounts

The link uses a **Gmail search URL**, such as:

```text
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**:

```powershell
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:

```powershell
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.