Skip to main content
Glama
multi-mailbox-gmail

multi-mailbox-gmail

by pkforge

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

Capability

Current status

Public GitHub repository and Codex installation

Available

Codex on Windows

Supported

Codex on macOS

Experimental — uses macOS Keychain

Codex on Linux

Experimental — requires Secret Service and secret-tool

Search multiple named Gmail accounts

Available after OAuth setup

Bring your own Google Desktop OAuth client

Available

One-click Connect @alias for non-developers

Not live yet — shared public OAuth client and Google verification are pending

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.

Available Tools

6 tools
connect_mailboxConnect a Gmail mailboxA

Connect a Gmail or Google Workspace account under a friendly alias. This opens Google sign-in in the user's browser and stores the resulting refresh token only on this computer.

Inputs: alias (required), replace.

disconnect_mailboxDisconnect a Gmail mailboxA
DestructiveIdempotent

Delete one mailbox alias and its encrypted OAuth token from this computer. This does not revoke the grant in the Google Account.

Inputs: alias (required).

list_mailboxesList named Gmail mailboxesA
Read-onlyIdempotent

List connected Gmail mailbox aliases. Use this when an alias is unknown or the user asks which mailboxes are available.

Inputs: no named parameters.

read_emailRead one Gmail messageA
Read-onlyIdempotent

Read a Gmail message returned by a mailbox search. Always pass both its source mailbox alias and message ID.

Inputs: mailbox (required), message_id (required).

search_all_mailboxesSearch every connected Gmail mailboxA
Read-onlyIdempotent

Search all connected Gmail and Google Workspace mailboxes in parallel using normal Gmail search syntax.

Inputs: query, max_results_per_mailbox.

search_mailboxesSearch selected Gmail mailboxesA
Read-onlyIdempotent

Search multiple named Gmail or Google Workspace mailboxes in parallel. Convert chat mentions such as @personal and @work into the mailboxes array without the @ prefix. The query uses normal Gmail search syntax.

Inputs: mailboxes (required), query, max_results_per_mailbox.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 6 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes: mailbox lifecycle management, searching, and reading. The only potential confusion is between search_all_mailboxes and search_mailboxes, but their names and descriptions clarify that one searches all and the other searches named mailboxes.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern: list_, connect_, disconnect_, search_, read_. The qualifiers such as all and mailboxes are applied uniformly, making the naming predictable and easy to follow.

    Tool Count5/5

    Six tools is well-scoped for a multi-mailbox Gmail server. Each tool earns its place by covering mailbox management, searching, and reading without unnecessary redundancy.

    Completeness4/5

    The core lifecycle and retrieval workflows are covered: connect, list, disconnect, search, and read. Missing capabilities like sending or modifying messages are not required by the apparent purpose, but a small gap exists for agents that need more than read-only access.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Connects AI assistants to multiple Gmail accounts simultaneously, enabling search, read, draft, send, and reply operations with per-account permission controls.
      54
      ISC
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables read and compose access to three Gmail accounts simultaneously, with tools for searching, viewing threads and messages, and drafting or sending replies.
      -
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to access multiple Gmail/Google Workspace accounts for searching and reading mail, calendars, and attachments.
      -