zemail

# Zemail **Semantic search over your Gmail, from inside Claude Code.** Zemail is a Claude Code plugin that gives Claude meaning-based search over your inbox. Instead of keyword-matching the last few pages of mail, it embeds your entire Gmail with [ZeroEntropy's zembed-1](https://zeroentropy.dev) and reranks results with zerank-2 — so *"budget discussion"* finds *"Q3 financial planning"*. Everything is local-first: your email content never leaves your machine. ## Why? Claude's built-in Gmail integration is a thin wrapper over Gmail's keyword search API. That means two things in practice: - **It only does keyword matching.** Ask about *"the budget discussion"* and it won't find the thread titled *"Q3 financial planning"* — the words don't overlap. You end up rephrasing queries until you stumble onto the right keywords, which defeats the point of having an assistant. - **It paginates over the live API.** Every search hits Gmail and returns one page of results, so Claude can only see the top handful per query. Anything older or further down the result list is invisible. For real questions ("who emailed me about hiring last quarter?") it's effectively useless. Zemail fixes both: your entire inbox gets embedded once with **zembed-1** (a state-of-the-art embedding model that actually understands meaning), then every query runs against the *whole* index and the top candidates get reranked by **zerank-2** (currently one of the best-performing rerankers available). The result is search that finds the right email even when you don't remember the exact words — across your full history, not just the last page. ## Features - **Full-inbox sync** — not just the latest page of results - **Semantic embeddings** via zembed-1 (searches by meaning) - **High-quality reranking** via zerank-2 (top results are actually relevant) - **Local storage** — embeddings and metadata stay on your machine ## Install From a Claude Code marketplace: ``` /plugin install zemail@<marketplace-name> ``` Or point Claude Code at a local clone: ```bash git clone https://github.com/<you>/zemail claude --plugin-dir ./zemail ``` ## Setup On install, Claude Code will prompt you for your **ZeroEntropy API key**. Grab a free one at [dashboard.zeroentropy.dev/api-keys](https://dashboard.zeroentropy.dev/api-keys) — takes 30 seconds and no credit card required. The first time you ask Claude something email-related, it will print a Google authorization URL — open it, grant read-only Gmail access, done. Zemail then syncs and indexes your inbox; subsequent searches are instant. ## Usage Just talk to Claude normally: - *"Find emails about the product launch"* - *"Who emailed me about the hiring pipeline?"* - *"Search for messages from the legal team about compliance"* ## How it works ``` Gmail API → Fetch all emails → Embed with zembed-1 → Local vector store ↓ User asks Claude → search_emails_tool → Embed query with zembed-1 ↓ Cosine similarity → Top 50 candidates ↓ Rerank with zerank-2 → Top 10 results ``` ## Tools exposed to Claude | Tool | Description | |------|-------------| | `set_api_key` | Save your ZeroEntropy API key | | `sync_emails` | Fetch and index Gmail messages | | `search_emails_tool` | Semantic search over indexed emails | | `get_email` | Read full email content by ID | | `authorize_gmail` | Manual OAuth code entry (for remote/SSH setups) | | `index_status` | Check index size and last sync time | ## Privacy Zemail requests the `gmail.readonly` OAuth scope — read-only access to your messages. Embeddings, metadata, and the OAuth token are stored on your local machine only. Message content is sent to ZeroEntropy's API for embedding and reranking; it is not stored there. Nothing is ever written back to Gmail. ## Requirements - Python 3.12+ - [uv](https://docs.astral.sh/uv/) - A Gmail account - A [ZeroEntropy API key](https://dashboard.zeroentropy.dev/api-keys) (free, no credit card) ## Development ```bash # Install dependencies uv pip install -e . # Run the MCP server directly python -m zemail.server # Quick search smoke test python -c "from zemail.server import search_emails_tool; print(search_emails_tool('test query'))" ``` ## License MIT