Skip to main content
Glama
gmail-fan

gmail-fan

by nvsd

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: mcp-gmail-oauth

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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      C
      maintenance
      Multi-account Google MCP server providing read access to Gmail and Calendar via stdio. Supports secure authentication for personal and work accounts with OAuth and keychain token storage.
      4
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A self-hostable Gmail MCP server that enables Gmail search/read, sending, replies, drafts, labels, and attachment downloads via MCP tools with OAuth authorization. Supports stdio and streamable HTTP transports.
      MIT
    • F
      license
      A
      quality
      B
      maintenance
      A local stdio MCP server that gives any MCP client one connection to all of the user's Gmail, Google Workspace and IMAP accounts at once, letting assistants list accounts, read messages and attachments, run full-text search across mailboxes, trigger syncs and export messages as .eml. It runs on the user's own computer with encrypted secrets and no intermediary server, so mail is fetched directly from the providers.
      9
      1
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP clients to search, read, send, reply, forward and draft mail, download and extract attachments, and manage labels, stars, archive and trash. It runs over stdio and talks straight to the Gmail API with the user's own OAuth credentials, so no third-party server sits in between.
      63 PyPI
      1
      MIT