Local LLM Labels Gmail Without Sending Email to Cloud

An open-source project called gmail-llm-labeler shows how a large language model can sort an inbox automatically. The tool, published by Cole Murray at https://github.com/ColeMurray/gmail-llm-labeler, connects to a Gmail account and applies labels to incoming messages based on categories the model assigns. It can run entirely against a local model, so message content does not have to be sent to a third-party service.

How the tool works

The project is a Python application that uses the Gmail API with OAuth 2.0 authentication. According to its documentation, setup requires creating a Google Cloud project, enabling the Gmail API, configuring an OAuth consent screen, and creating an OAuth client ID of the Desktop app type. The resulting credentials.json file is downloaded into the project, and the first run opens a browser to complete authentication and generate a token.json file.

The application requests the https://www.googleapis.com/auth/gmail.modify scope, which the README notes allows reading messages and modifying labels. Its two headline features are LLM categorization and automatic labeling, the latter described as applying Gmail labels based on the categories the model returns.

Local or cloud models

The tool supports two model backends. One option is OpenAI’s GPT models, which require a paid API key. The other is Ollama, listed in the documentation as a free option that runs on the user’s own machine. Installation for the local path is handled with pip install ".[ollama]", and the example configuration references an Ollama model named gpt-oss:20b. Configuration is supplied through a .env file containing either an OpenAI key or the Ollama host and model settings.

Running a model locally through Ollama means the email text stays on the user’s hardware rather than being uploaded to an external provider. That distinction matters for anyone who handles sensitive correspondence and wants automated sorting without exposing message contents to a cloud service.

Testing and tracking

The project includes a dry run mode so categorization can be tested without applying any labels, which lets users confirm the model’s behavior before it touches their inbox. It also ships with an extract-transform-load pipeline for batch processing, SQLite-based tracking of processed emails, and metrics and monitoring features.

The functionality is exposed through a command line interface accessed with the gmail-pipeline command. The README lists subcommands and flags including run, --dry-run, --preview, show-metrics, validate-config, and generate-config. The codebase is written entirely in Python and released under the MIT license.

A practical pattern for inbox sorting

What makes the project notable is not a single benchmark but the pattern it demonstrates. A small local model, the Gmail API, and a labeling step are enough to categorize an inbox automatically. Because the same code can point at either a local Ollama instance or a hosted OpenAI model, developers can start with whichever fits their privacy needs and hardware, then adjust the configuration later without rewriting the integration.