Multi Mailbox Gmail for Codex

An open-source Codex plugin for connecting and searching multiple Gmail and Google Workspace accounts by friendly aliases such as @personal and @work.

It extends Codex with a local MCP server and mailbox-aware instructions, so a request such as Search @personal and @work for recent invoices searches both selected accounts and identifies the source mailbox for every result. Mail access is read-only.

Release status

The repository is public, but it is currently a developer preview. Until the shared OAuth client is added, an outside user can install the Codex plugin but must supply their own Google Desktop OAuth credentials before connecting a mailbox.

Related MCP server: multi-gmail-mcp-server

Install in Codex

npx codex-marketplace add pkforge/multi-mailbox-gmail --plugin

Start a new Codex task after installation so the plugin's skill and MCP tools are loaded.

Connect mailboxes in chat

Once the shared public OAuth client is live, users will start a new Codex task and say:

Connect @personal
Connect @work

Each command opens Google's account chooser. Pick the account that should own that alias and approve read-only Gmail access. Repeat for as many accounts as you need.

The planned public build will use one shared Google Desktop app identity so end users do not need a Google Cloud account or developer setup. OAuth happens directly between this local plugin and Google: there is no publisher backend, database, analytics, or telemetry. The plugin requests only https://www.googleapis.com/auth/gmail.readonly. Refresh tokens are encrypted for the current Windows user with DPAPI; aliases and account email addresses are stored as local metadata under %LOCALAPPDATA%\MultiMailboxGmail.

Current setup: use your own OAuth client

Organizations that prefer their own Google Cloud project can create a Desktop OAuth client, enable the Gmail API, and either pass its downloaded JSON to the CLI or set MULTI_MAILBOX_GMAIL_OAUTH_CLIENT_FILE.

npm.cmd install
npm.cmd run mailbox -- add personal C:\path\to\oauth-client.json
npm.cmd run mailbox -- add work C:\path\to\oauth-client.json
npm.cmd run mailbox -- list

Each add command opens Google sign-in. Choose the account that should own that alias.

Remove locally stored credentials with:

npm.cmd run mailbox -- remove work

This removes the local encrypted token. You can separately revoke the app from the Google Account security page if desired.

Use in chat

• Search @personal and @work for invoices from the last 90 days.

• Search @finance for unread mail with attachments.

• Search all mailboxes for subject:renewal newer_than:1y.

The plugin returns each message with its source alias, so identical messages remain attributable to the correct mailbox.

Public release work remaining

Before non-developers can use Connect @alias without Google Cloud setup, the project owner must:

1. Finish the Google OAuth consent-screen configuration.

2. Create and publish the installed-app OAuth client identity.

3. Test the end-to-end Codex connection flow with multiple accounts.

4. Submit the restricted Gmail read-only scope for Google's public-app verification.

During review, Google may show an unverified-app warning and enforce its unverified-user cap. The source code and bring-your-own-client path remain usable.

This is an independent community project and is not affiliated with or endorsed by Google or OpenAI.

See Privacy, Security, and the Google verification package.