AutoMFA

Lightweight CLI / shortcut to speed up the process of inserting Email MFA codes using Local (or external) LLMs.

Features

• Multiple Gmail account support
• Secure local credential storage
• Automatic token refresh
• AI-powered MFA code extraction (OpenAI or Ollama)
• Copies code to clipboard automatically
• Keyboard shortcut support for quick access

Setup

Install with uv:

uv venv
venv 
uv pip install -e .

Run guided setup:

automfa init

This will help you:

1. Set up Google Cloud OAuth credentials
2. Choose AI provider (OpenAI or Ollama-powered Local LLMs)
3. Configure your first Gmail account

Manual Setup

If you prefer manual setup, create .env file:

GMAIL_CLIENT_ID=your_client_id_here
GMAIL_CLIENT_SECRET=your_client_secret_here
OPENAI_API_KEY=your_openai_api_key  # If using OpenAI

The tool will look for .env in:

1. Current directory (where you run the command)
2. Project root (where automfa is installed)

Getting Gmail OAuth Credentials

1. Go to Google Cloud Console
2. Create new project or select existing
3. Enable Gmail API
4. Create OAuth 2.0 credentials (Desktop application)
5. Important: Add test users in OAuth consent screen if in testing mode

AI Provider Options

OpenAI:

• Get API key from OpenAI Platform
• Available models:
  • Flagship: gpt-4o, gpt-4.1
  • Cost-optimized: o4-mini (recommended), gpt-4o-mini, gpt-4.1-mini, o3-mini
  • Custom: Any model name you have access to

Ollama:

• Install from ollama.ai
• Run ollama serve to start
• Recommended models: gemma2:2b, llama3.2:3b, mistral:7b

Usage

Check setup:

automfa check

Configure AI provider:

# Interactive mode - shows current config and prompts for changes
automfa config

# Change provider directly
automfa config --provider openai
automfa config --provider ollama

# Change model directly
automfa config --model o4-mini
automfa config --model gemma2:2b

# Change both
automfa config --provider ollama --model mistral:7b

Add Gmail account:

# Will prompt oauth in browser
automfa add personal
automfa add work

List accounts:

automfa list

Find and copy MFA code:

# From specific account
automfa get personal

# From all accounts (stops at first code found)
automfa get -a

# Check emails from last 5 minutes
automfa get personal -m 5

# If only one account configured
automfa get

Remove account:

automfa remove personal

Keyboard Shortcut Setup

To run automfa with a keyboard shortcut, you'll need to create a command that uses the full path to Python in your virtual environment.

Find your command path:

# From your automfa directory, run:
echo "$PWD/.venv/bin/python -m automfa.cli get -a -m 10"

This will output something like:

/Users/yourname/automfa/.venv/bin/python -m automfa.cli get -a -m 10

Set up keyboard shortcut:

Option 1: macOS Shortcuts app Copy the shortcut config from the screenshot:

Option 2: Raycast

1. Create a new Script Command
2. Language: Bash
3. Script:

   #!/bin/bash
   /path/to/your/automfa/.venv/bin/python -m automfa.cli get -a -m 10

4. Set hotkey in extension settings

Option 3: Alfred

1. Create new Workflow
2. Add Hotkey trigger
3. Add "Run Script" action
4. Script: Your full command path

Option 4: BetterTouchTool

1. Add keyboard shortcut
2. Action: Execute Terminal Command (Synchronously)
3. Command: Your full command path

Data Storage

All data stored in ~/.automfa/:

• config.json - Model provider configuration
• accounts.json - Encrypted account information
• token_*.pickle - Gmail OAuth tokens per account
• credentials.json - Shared Google OAuth credentials