The AI-native command center for Gmail and Google Workspace

Google MailPilot is the renamed successor to Gmail Secretary, built so LLMs can read, triage, respond to, and calendar-manage Gmail with a production-grade MCP control plane.

⚠️ Release Notice: v5.0.0 is the first public release under the Google MailPilot brand; it fixes MCP tool registration, tightens triage/compose coverage, adds new booking-link helpers, and keeps every mutation human-in-the-loop.

Release highlights:

• Tools now register as soon as workspace_secretary.tools imports, preventing FastMCP registration bugs.
• Triage/compose tooling gained synchronous tests plus tests/test_triage_priority_emails.py and tests/test_web_compose.py to cover CLI-aware workflows.
• Engine/web routes, booking links, and raw: continuation-state handling now align with Google MailPilot expectations.

We believe in transparency. Here is the current readiness of our stack:

A Google MailPilot IMAP/SMTP control plane for AI agents with calendar integration

Built for LLMs that need to read, search, triage, and respond to email autonomously. Not just an MCP wrapper — a full-featured IMAP control plane engineered for AI orchestration workflows.

📚 Documentation · 🏗️ Architecture · ⚡ Quick Start

Most email integrations for AI are thin API wrappers. They poll. They re-fetch. They timeout. They don't understand email threading, modification sequences, or push notifications.

Google MailPilot is different. It's a production-grade IMAP control plane that:

• Syncs intelligently — CONDSTORE tracks what changed, IDLE pushes new mail instantly
• Caches locally — SQLite or PostgreSQL, your AI reads from local DB in milliseconds
• Understands Gmail — Native X-GM-THRID threading, X-GM-LABELS, X-GM-RAW search
• Never sends without approval — Human-in-the-loop by design, drafts first

We implement these IMAP extensions for efficient, real-time email sync:

Real benchmarks against a 50,000 email mailbox:

Traditional Sync:
  1. SELECT INBOX
  2. FETCH 1:* (FLAGS)        ← Downloads ALL flags every time
  3. Compare with cache
  4. Fetch changed messages

CONDSTORE Sync:
  1. SELECT INBOX
  2. Compare HIGHESTMODSEQ    ← Single integer comparison
  3. If unchanged → done      ← Skip everything
  4. If changed → FETCH 1:* (FLAGS) CHANGEDSINCE <modseq>
                              ← Only changed messages

Dual-process design separating sync from AI interface:

┌─────────────────────────────────────────────────────────────────┐
│                        AI Layer (Claude, etc.)                  │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                     MCP Server (read-only)                      │
│  • Exposes 25+ tools for email/calendar operations              │
│  • Reads directly from local database                           │
│  • Mutations proxied to Engine API                              │
└─────────────────────────────────────────────────────────────────┘
                                │
              ┌─────────────────┴─────────────────┐
              ▼                                   ▼
┌──────────────────────────┐        ┌──────────────────────────┐
│   SQLite / PostgreSQL    │        │     Secretary Engine     │
│  • Email cache (FTS5)    │◀───────│  • IMAP sync (CONDSTORE) │
│  • Gmail labels (JSONB)  │        │  • IDLE monitor          │
│  • Embeddings (pgvector) │        │  • OAuth2 management     │
└──────────────────────────┘        │  • SMTP send/draft       │
                                    └──────────────────────────┘
                                              │
                                              ▼
                                    ┌──────────────────┐
                                    │   Gmail IMAP     │
                                    │   Gmail SMTP     │
                                    │   Calendar API   │
                                    └──────────────────┘

Calendar Integration:

• ⚡ Instant Calendar Access: Sub-50ms queries via intelligent caching layer
• 🌐 Offline-First Operations: Create/edit/delete events without internet, sync transparently
• 🔄 Background Sync Worker: Autonomous daemon syncs every 60s using Google Calendar API sync tokens
• 🏷️ Status Indicators: Visual badges show pending/synced/conflict states for offline operations
• ⚙️ Multi-Calendar Support: Select which calendars to display via web UI settings

Email Intelligence:

Every email is analyzed for actionable signals:

signals = {
    "is_addressed_to_me": True,      # In To: field, not just CC
    "mentions_my_name": True,        # Name appears in body
    "has_question": True,            # Contains "?" or question phrases
    "mentions_deadline": True,       # "EOD", "ASAP", "by Friday"
    "mentions_meeting": True,        # Scheduling keywords detected
    "is_from_vip": True,             # Sender in configured VIP list
    "has_attachments": True,         # PDF, DOCX, etc.
    "attachment_filenames": ["Q4_Report.pdf"]
}

The AI never sends email without explicit approval.

User: "Reply to Sarah saying I'll attend the meeting"

AI: I've drafted this reply:

    To: sarah@company.com
    Subject: Re: Team Meeting Tomorrow

    Hi Sarah,

    I'll be there. Looking forward to it!

    Best regards

    Send this email? (yes/no)

User: "yes"
AI: ✓ Email sent successfully

Bulk operations require approval with confidence tiers:

• Docker and Docker Compose
• Gmail account with App Password (or OAuth2)
• Google Cloud project (for Calendar integration)

git clone https://github.com/johnneerdael/google-mailpilot.git
cd google-mailpilot
cp config.sample.yaml config/config.yaml

# config/config.yaml
imap:
  host: imap.gmail.com
  port: 993
  username: your-email@gmail.com
  password: your-app-password    # Gmail App Password

user:
  email: your-email@gmail.com
  first_name: Your
  last_name: Name
  timezone: America/New_York
  working_hours:
    start: "09:00"
    end: "18:00"
  vip_senders:
    - ceo@company.com
    - important-client@example.com

database:
  backend: sqlite               # or "postgres" for embeddings
  path: /app/config/secretary.db

bearer_auth:
  enabled: true
  token: "generate-with-uuidgen"

docker-compose up -d

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "secretary": {
      "url": "http://localhost:8000/mcp",
      "headers": {
        "Authorization": "Bearer your-token-here"
      }
    }
  }
}

CREATE TABLE emails (
    uid INTEGER,
    folder TEXT,
    message_id TEXT UNIQUE,
    gmail_thread_id BIGINT,        -- X-GM-THRID
    gmail_msgid BIGINT,            -- X-GM-MSGID
    gmail_labels JSONB,            -- Full label set
    subject TEXT,
    from_addr TEXT,
    to_addr TEXT,
    date TIMESTAMPTZ,
    internal_date TIMESTAMPTZ,     -- INTERNALDATE
    body_text TEXT,
    body_html TEXT,
    flags TEXT,
    modseq BIGINT,                 -- CONDSTORE sequence
    has_attachments BOOLEAN,
    attachment_filenames JSONB,
    -- FTS5 index on subject, from_addr, to_addr, body_text
);

CREATE TABLE folder_state (
    folder TEXT PRIMARY KEY,
    uidvalidity INTEGER,
    uidnext INTEGER,
    highestmodseq BIGINT           -- For CONDSTORE sync
);

• Plain text passwords
• OAuth refresh tokens in logs
• Email content in error messages

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run locally
python -m workspace_secretary.engine.api &  # Start engine
python -m workspace_secretary.server        # Start MCP server

MIT License — see LICENSE for details.

Built for AI agents that take email seriously.
GitHub · Documentation · Model Context Protocol