Automate Gmail Tasks with Standalone OAuth

Provides command-line Gmail access for a Google Workspace account through standalone OAuth scripts, with no MCP server required. Personal Gmail accounts are not supported. First-time setup authenticates via a browser flow:

python scripts/auth.py login
python scripts/auth.py status
python scripts/auth.py logout

All operations run through scripts/gmail.py, which auto-authenticates on first use if not already logged in. Searching supports full Gmail query syntax plus flags for result limit, label filtering, and including spam/trash: python scripts/gmail.py search "from:someone@example.com is:unread", search --limit 20, search --label INBOX --limit 10, search "subject:important" --include-spam-trash. Reading a message supports three response levels: full content (gmail.py get MESSAGE_ID), metadata/headers only (--format metadata), or minimal, IDs only (--format minimal).

Sending supports plain text, CC/BCC, sending from a configured alias, and HTML bodies: gmail.py send --to "user@example.com" --subject "Hello" --body "Message body", with --cc/--bcc flags, a --from "Name <alias@domain>" flag for a Gmail-configured alias, and an --html flag for an HTML body like --body "<h1>Hello</h1><p>HTML content</p>". Drafts are created and sent separately: create-draft --to ... --subject ... --body ... followed by send-draft DRAFT_ID. Message state is changed through label modification, modify MESSAGE_ID --remove-label UNREAD to mark read, --add-label UNREAD to mark unread, --remove-label INBOX to archive, --add-label STARRED/--remove-label STARRED to star or unstar, --add-label IMPORTANT to mark important, and multiple label changes can be combined in a single modify call. All Gmail labels, system and user-created, list via gmail.py list-labels.

Gmail's query syntax is documented directly: from:, to:, subject:, is:unread, is:starred, is:important, has:attachment, after:/before: dates, newer_than:7d, older_than:1m, label:work, and in:inbox/in:sent/in:trash, combinable with a space for AND, OR, or a leading - for NOT, for example "from:boss@company.com is:unread newer_than:1d", "subject:urgent OR subject:important", or "from:newsletter@example.com -is:starred". Common label IDs are listed for direct use in modify calls: INBOX, SENT, DRAFT, SPAM, TRASH, STARRED, IMPORTANT, UNREAD.

OAuth tokens are stored in the operating system's keyring rather than in plaintext, macOS Keychain, Windows Credential Locker, or the Linux Secret Service API (GNOME Keyring, KDE Wallet), under the service name gmail-skill-oauth, and refresh automatically when expired using Google's cloud function.

Use it when searching, reading, or sending Gmail messages from the command line without an MCP server, automating inbox workflows for a Google Workspace account, or needing a lightweight, standalone-OAuth Gmail integration. Skip it for personal Gmail accounts, which are not supported.

Input is a Gmail search query, message or draft ID, or message content to send. Output is search results, message content at the requested detail level, a sent message or draft, an updated label state, or the label list.

Integrates with the Gmail API via Google OAuth, storing tokens in the OS-native keyring (macOS Keychain, Windows Credential Locker, or Linux Secret Service API) under the gmail-skill-oauth service name, with automatic token refresh through Google's cloud function.

Developers and automators on a Google Workspace account who want to search, read, send, or organize Gmail from the command line without standing up an MCP server.