# mail-index **Category:** πŸ’¬ Communication **Repository:** https://github.com/alunsoldantarctica/mail-index **Views:** 0 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/mail-index ## Description Local-first, read-only MCP server for recall over your Gmail: search, contacts, threads, digests. ## Claude Desktop Quick Installation Heuristic fallback β€” verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low): ```json "mcpServers": { "mail-index": { "command": "npx", "args": ["-y","mail-index"] } } ``` ## Documentation & README # mail-index [![npm version](https://img.shields.io/npm/v/mail-index?logo=npm&color=cb3837)](https://www.npmjs.com/package/mail-index) [![npm downloads](https://img.shields.io/npm/dm/mail-index?logo=npm&color=cb3837)](https://www.npmjs.com/package/mail-index) [![GitHub stars](https://img.shields.io/github/stars/unsoldgroup/mail-index?logo=github)](https://github.com/unsoldgroup/mail-index/stargazers) [![GitHub forks](https://img.shields.io/github/forks/unsoldgroup/mail-index?logo=github)](https://github.com/unsoldgroup/mail-index/network/members) [![CI](https://github.com/unsoldgroup/mail-index/actions/workflows/ci.yml/badge.svg)](https://github.com/unsoldgroup/mail-index/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) ![Node](https://img.shields.io/badge/node-%E2%89%A524-3c873a) ![deps](https://img.shields.io/badge/native%20deps-none-brightgreen) mail-index downloads a **preview of your whole inbox** to your machine, then smartly fetches the full text of the messages that matter as you use it. That local index lets your AI agent run **true summarization and recall over your entire mailbox** β€” instead of being trapped behind Gmail's search bar. It works through a **local MCP server**, so any agent (Claude, Codex, any MCP client) can query it. Local-first β€” the default index never leaves your machine. Operators who need an always-on connector can instead deploy the optional, single-tenant [remote Worker Deployment](docs/INSTALL-worker.md) in their own Cloudflare account; mail-index operates no hosting service. Read-only by default β€” it never sends or mutates your mail unless you explicitly opt into archive + label edits (a least-privilege `gmail.modify` re-auth; never send or delete). See [ADR-0007](docs/adr/0007-opt-in-mailbox-writes.md).

Claude answering a vague inbox question through the mail-index MCP server, locally, with zero network calls
Ask a vague question β†’ one local MCP call β†’ ranked, snippet-first answer. Interactive version β†’

> **Status: v1.5 β€” published.** Progressive sync, the correspondence graph, the > interest engine, curation, the full 23-tool MCP surface, and the write-back > loops are built and tested β€” and `mail-index` is live on > **[npm](https://www.npmjs.com/package/mail-index)** with a > **[`.mcpb` bundle](https://github.com/unsoldgroup/mail-index/releases/latest)**. > Still in progress: the bundled Option A OAuth client and signed one-click > installers. Architecture lives in > **[docs/PLAN.md](docs/PLAN.md)**; start with **[docs/INSTALL.md](docs/INSTALL.md)**; > every release is recorded in **[CHANGELOG.md](CHANGELOG.md)**. > [!TIP] > **New in v1.5 β€” the optional remote Deployment.** mail-index can now also run > as a **single-tenant Cloudflare Worker in your own account**: always-on, synced > on a cron, and reachable by remote agents over authenticated MCP (plus a small > A2A surface). It serves the _same_ tool registry as the local server, backed by > a **D1** storage driver that passes the same FTS ranking conformance suite, and > it can **push** β€” Trigger rules match new mail as it lands and fire signed > webhooks. Long O(N) work becomes a queued **Job** instead of a command > handback. You can seed a fresh Deployment straight from your existing local > index with `mail-index export` β†’ D1 import, so it starts with your history > already indexed. **The local CLI + stdio path is unchanged and stays the > default**, and mail-index still operates no hosting service β€” the Worker is > code you deploy to infrastructure you own. > See **[docs/INSTALL-worker.md](docs/INSTALL-worker.md)**, > **[docs/WORKER-SEED.md](docs/WORKER-SEED.md)**, > **[ADR-0008](docs/adr/0008-self-hosted-remote-deployment.md)**. > > Also new locally: every MCP response carries a **freshness block** and any > stale read now auto-triggers a background sync (previously only the digest > composites did). > [!TIP] > **From v1.4 β€” opt-in mailbox writes + human-readable labels.** > mail-index can **archive** a message and **edit its labels** directly on > Gmail β€” via the `archive` / `label` CLI commands and the `archive_message` / > `modify_labels` MCP tools, on both the gog and gws adapters. It stays > **read-only by default**: writes are unreachable until you opt in with a > _least-privilege_ `gmail.modify` grant (**never** send or delete) β€” enable per > account with `mail-index setup --account --enable-writes` or the > bundled `scripts/enable-writes.sh`. Labels render as their **human names** > everywhere (the index caches Gmail's label catalogue and resolves > `Label_3546…` β†’ _"Expedition Insure"_ in both directions), and you can pass a > friendly label name to `label --add/--remove`. > See **[ADR-0007](docs/adr/0007-opt-in-mailbox-writes.md)**. --- ## How it works 1. **Progressive sync** β€” metadata for the whole mailbox in minutes; bodies fetched selectively. 2. **Graph** β€” contacts, domains, threads; centrality + communities over your _human_ (non-bulk) mail. 3. **Interest** β€” an engagement score per contact from read/reply/star/importance signals. A _seed for your curation_, not an autonomous decision. 4. **Curate** β€” you (via your agent, or a CLI wizard) confirm who/what matters; that profile drives which bodies get fetched. 5. **Query** β€” your agent searches, traverses the graph, and reads the messages that matter, all locally via MCP.

mail-index prewarms a local SQLite index with the important messages, then the MCP server serves the agent from it, fetching from Gmail again only on a miss
Important messages prewarm a local index; the MCP reads from it, touching Gmail again only when a needed body isn't there yet. Interactive version β†’

## Quick start Requires **Node 24+** and a Gmail `MailSource` adapter β€” **`gog`** (recommended) or **`gws`**. Reading Gmail needs a Google OAuth client, and you get one **two ways**: use the **mail-index beta client** (skip Google Cloud entirely; [request access](https://github.com/unsoldgroup/mail-index/issues/new?template=beta_access.yml) to join the ~100-user test list) or **bring your own** Google Cloud client (no cap, no request β€” we walk you through it). See [docs/INSTALL.md Β§2](docs/INSTALL.md#2-connect-a-mailbox-pick-an-oauth-path) and [docs/oauth-and-verification.md](docs/oauth-and-verification.md). ```sh npm install -g mail-index # or: pnpm add -g mail-index mail-index init # scaffold the config # …connect a mailbox (own OAuth client, read-only) β€” see docs/INSTALL.md Β§2 / agent-install.md… mail-index sync --account personal --since 6mo mail-index graph build --account personal mail-index search "that contract we discussed" ``` _(Prefer source? `git clone …`, `pnpm install && pnpm build`, then run the bins as `node dist/cli/index.js …`.)_ ### Add to Claude The MCP server registers in one step, but it still needs a mailbox connected first (see the walkthrough). A `.mcpb`/`claude mcp add` only **adds the server** β€” it doesn't install the adapter, sign you in, or sync. - **Claude Code:** `claude mcp add --transport stdio mail-index -- npx -y -p mail-index mail-index-mcp` (on **Windows**, prefix with `cmd /c`: `… -- cmd /c npx -y -p mail-index mail-index-mcp` β€” bare `npx`/`.cmd` won't spawn. See [docs/INSTALL.md Β§7](docs/INSTALL.md).) - **Any MCP client (manual):** ```jsonc { "mcpServers": { "mail-index": { "command": "mail-index-mcp" } } } ``` - **Claude Desktop:** download the **[`.mcpb` bundle](https://github.com/unsoldgroup/mail-index/releases/latest/download/mail-index.mcpb)** and double-click it (unsigned during beta β€” you may need to allow it in System Settings / Windows SmartScreen). The bundle is **self-contained** (ships its own dependencies, run by Claude Desktop's bundled Node β€” no npx, network, or system Node needed) so it installs identically on Windows/macOS/Linux. A signed all-in-one installer that _also_ installs the adapter, signs you in, and syncs is still in progress; there is no `claude://` install link. **Teach your agent the common moves.** The MCP server already tells the agent _when_ to reach for it (purchases, receipts, bookings, "who said what", "catch me up"), and the repo ships a Claude **[Agent Skill](skills/mail-index/SKILL.md)** with the typical recipes (find purchases, catch up, find a contact's mail, summarize a sender). Drop it in for Claude Code/Desktop: ```sh mkdir -p ~/.claude/skills && cp -R skills/mail-index ~/.claude/skills/ ``` Full walkthrough (auth, curation, enrichment, scheduled sync, desktop-app gotchas) β†’ **[docs/INSTALL.md](docs/INSTALL.md)**. Driving setup with an agent β†’ **[docs/agent-install.md](docs/agent-install.md)**. ## What to expect β€” time & storage The index keeps metadata for every message and full text only where it earns it, so it grows with message _count_, not mailbox size β€” about **1.5% of your Gmail**. First sync runs ~50 messages/min (one-time, incremental after); search is instant. Start with `--since 1mo` for value in minutes, then expand. Sizing table & growth path β†’ **[docs/INSTALL.md Β§9](docs/INSTALL.md#9-grow-your-index-intelligently)**. ## Why it's lighter than Gmail search Stock Gmail-API MCPs are query-based **lookup** tools β€” exact query, a network round-trip per call, raw payloads dumped into the model's context. mail-index answers _vague_ questions from a local **recall** index. Across a 100-question suite on a real mailbox it answered every question for **15Γ— fewer tokens** β€” and the gap widens exactly where a query-based MCP has no primitive at all: summarizing, relationships, and commitments.

Token savings by category across 100 inbox questions, mail-index vs a stock Gmail-API MCP: Retrieval 3.0Γ—, Logistics 4.9Γ—, Scheduling 9.2Γ—, Commitments 9.6Γ—, Finance 13.0Γ—, Account 20.3Γ—, Relationship 24.7Γ—, Summarize 32.8Γ— β€” 15.3Γ— overall.

Per-category tables, the read-one-message comparison, the tool-by-tool landscape, and how to reproduce it all β†’ **[docs/COMPARISON.md](docs/COMPARISON.md)**. ## Stack TypeScript Β· `node:sqlite` (no native deps) Β· SQLite FTS5 Β· Graphology Β· `@modelcontextprotocol/sdk`. Node 24+. Pluggable `MailSource` adapters; ships two Gmail transports β€” [`gog`](https://github.com/openclaw/gogcli) (recommended) and Google's [`gws`](https://github.com/googleworkspace/cli). ## CLI Two bins ship: `mail-index` (CLI) and `mail-index-mcp` (the stdio MCP server). ``` mail-index init Scaffold the operator config + data dir mail-index sync --account [--since 30d|1mo] [--all] [--query ] [--limit N] mail-index sync --all-accounts Sync every account by its policy presets mail-index enrich --account [--profile | --rule direct|all] [--sender ] [--match ] [--limit N] mail-index graph build [--account | --all-accounts] mail-index curate [--account ] Interactive curation wizard (no-agent fallback) mail-index compact [--account ] [--now] Demote summarized bulk bodies (ADR-0003) mail-index search [--account ] [--limit N] [--enrich] mail-index show Print a message (auto-enriches a meta row) mail-index open Print the provider web URL (no fetch) mail-index archive Archive (drop INBOX) β€” opt-in write; needs gmail.modify mail-index label [--add ]... [--remove ]... Opt-in write; needs gmail.modify mail-index status [--json] Per-account freshness + counts ``` Writes are off by default. Enable archive + label edits for an account with `mail-index setup --account --enable-writes` (or the bundled `scripts/enable-writes.sh `) β€” a least-privilege `gmail.modify` grant (never send or delete). See [ADR-0007](docs/adr/0007-opt-in-mailbox-writes.md). ## Documentation - **[docs/INSTALL.md](docs/INSTALL.md)** β€” generic onboarding (install, authenticate a MailSource, init, sync, curate, enrich, add the MCP server, scheduled-sync snippet). - **[docs/MCP.md](docs/MCP.md)** β€” the 18-tool MCP reference for agent integrators: args, compact result shapes, the `index_as_of` freshness + command-handback contracts. - **[docs/ADAPTERS.md](docs/ADAPTERS.md)** β€” the `MailSource` contract and how to write + contract-test a new adapter (`gws`, `gog`, `gmail-rest`). - **[docs/INSTALL-worker.md](docs/INSTALL-worker.md)** β€” deploy the optional single-tenant remote Worker to your own Cloudflare account: D1 / Queue / KV resources, secrets, the operator allowlist, connecting an agent, and a verification checklist. - **[docs/WORKER-SEED.md](docs/WORKER-SEED.md)** β€” seed a fresh Deployment's D1 from an existing local index (`mail-index export` β†’ import), instead of re-syncing the whole mailbox from Gmail. - **[docs/PLAN-worker.md](docs/PLAN-worker.md)** β€” the remote-Deployment design: locked decisions, milestones, and the local↔remote parity constraints. - **[CHANGELOG.md](CHANGELOG.md)** β€” what changed in every released version. - **[docs/PLAN.md](docs/PLAN.md)** β€” architecture, data model, and the key decisions (ADR digest). - **[SECURITY.md](.github/SECURITY.md)** + **[docs/THREAT-MODEL.md](docs/THREAT-MODEL.md)** β€” privacy posture, trust boundaries, prompt-injection stance, and a "verify our claims yourself" runbook. The local-only promise is enforced in CI by an [egress guard test](test/egress-guard.test.ts) β€” the core (`src/`) makes no network calls; the one exception is the opt-out launch-shim self-updater (`bin/selfupdate.mjs`, throttled npm-version check, `MAIL_INDEX_NO_AUTOUPDATE=1` to disable), audited by the same guard. ## About Built by **[Unsold Group](https://unsold.group/al)** β€” a travel & insurtech company building the groundwork to operate as an AI-native business: local-first, agent-native infrastructure that gives AI real, queryable context to work from. mail-index is one piece of that β€” giving agents durable memory of a mailbox without handing them the keys to it. More: **[unsold.group/al](https://unsold.group/al)** ## Project growth [![Star History Chart](https://api.star-history.com/svg?repos=unsoldgroup/mail-index&type=Date)](https://star-history.com/#unsoldgroup/mail-index&Date) ## Feedback & contact There's **no telemetry** β€” we only know what you tell us, so feedback is genuinely welcome: - πŸ’¬ **[Discussions](https://github.com/unsoldgroup/mail-index/discussions)** β€” questions, ideas, how you use it - 🐞 **[Report a bug](https://github.com/unsoldgroup/mail-index/issues/new?template=bug_report.yml)** Β· πŸ’‘ **[Request a feature](https://github.com/unsoldgroup/mail-index/issues/new?template=feature_request.yml)** - πŸ”’ Security/privacy issues β†’ **[SECURITY.md](.github/SECURITY.md)** (private) - 🌐 **[unsold.group/al](https://unsold.group/al)** Inside your agent you can also just say _"report a mail-index bug"_ β€” the MCP server points the agent to a GitHub link for you to submit (it never sends anything itself). See **[SUPPORT.md](.github/SUPPORT.md)**. ## License [MIT](LICENSE)