gmail-fan

Local-first macOS Gmail gateway: synchronize several Gmail or Google Workspace accounts into SQLite, search them quickly, and expose the same operations through a JSON CLI and a local stdio MCP server.

Gmail is the source of truth. OAuth tokens live in the macOS Keychain. There is no bundled model, embeddings index, or model-provider SDK.

Requirements

• macOS (Keychain + LaunchAgent)

• Bun 1.4 or newer

• A Google Cloud project with the Gmail API enabled and an OAuth Desktop client JSON

Related MCP server: Gmail Local MCP

Install and first account

bun install
bun run build
bun src/cli/main.ts init --oauth-client ./client_secret.json
bun src/cli/main.ts accounts add --alias work
bun src/cli/main.ts sync
bun src/cli/main.ts search "quarterly planning" --json

Production paths:

~/Library/Application Support/gmail-fan/
~/Library/Logs/gmail-fan/

Development

bun install
bun run test:unit
bun run test:integration
bun run typecheck
bun run check
bun run build

Architecture

Gmail accounts
      ↓
Gmail API + separate OAuth grant per account
      ↓
Synchronization service
      ↓
SQLite + FTS5
      ↓
Shared application service layer
      ↓
CLI            Local MCP server (stdio)

Decisions: docs/adr. Security: docs/security.md. CLI: docs/cli.md. MCP: docs/mcp.md. Demo: docs/demo.md.