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 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:
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 — 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
Development
# 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
thedotmack