# 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](https://bun.com) 1.4 or newer
- A Google Cloud project with the Gmail API enabled and an **OAuth Desktop** client JSON

## Install and first account

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

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

## Development

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

## Architecture

```text
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`](docs/adr). Security: [`docs/security.md`](docs/security.md). CLI: [`docs/cli.md`](docs/cli.md). MCP: [`docs/mcp.md`](docs/mcp.md). Demo: [`docs/demo.md`](docs/demo.md).