google-multi-account-mcp

A self-hosted remote MCP connector that gives Claude (or any MCP client that supports OAuth) access to several Gmail and Google Calendar accounts at once: personal Gmail and any number of Google Workspace accounts, side by side, in one connector.

Built-in Google connectors typically hold one Google identity; connecting a second replaces the first. This server holds as many as you connect and routes each call by account label, address or domain, or fans out across all of them.

What you can ask for

• "What's unread across all my inboxes since yesterday?"

• "Find the Acme contract thread in my work account and draft a reply confirming Thursday."

• "Forward the last three invoices from billing@supplier to my bookkeeping agent."

• "When am I free for an hour next week across all my calendars?"

• "Accept the board meeting invite on my work calendar."

Related MCP server: IMAP MCP Server

Features

• Multi-account: connect any number of Google accounts under short labels (work, personal, client-a) and pick one per call by label, address or domain. Read and search tools accept account: "all".

• Gmail: search, read threads and messages, fetch attachments, labels, archive / read / star, trash, drafts with attachments (uploaded or re-used from another email), replies with quoting, and inline forwards that keep attachments.

• Calendar: list calendars and events, merged timelines across accounts, create / update / delete events, respond to invites, free/busy across every account. Times without an offset are read in your configured time zone.

• Safe sending by default: mail to arbitrary recipients is always draft first, then gmail_send_draft, so each send is a separate, reviewable tool call.

• Optional auto-forward allowlist: forward_to_allowlist sends immediately, but only to addresses you configure (for example an AI agent's inbox), so it can be set to "always allow" in your MCP client without opening a general send path.

• Account health: list_accounts with check: true tests every mailbox and flags any that need reconnecting.

• Audit log: every write is recorded and queryable with the audit_log tool.

• Guided setup: a /setup page on your server shows exactly what to paste into Google Cloud and Claude, and checks your configuration live.

Security model

See SECURITY.md to report a vulnerability.

Requirements

• A host with a public HTTPS URL (Render, Fly.io, a VPS behind a reverse proxy, etc.)

• PostgreSQL

• Node 20+ (or Docker)

• Your own Google Cloud project (free). Every deployment uses its own OAuth client; there is no shared app.

Setup

Allow about 15 minutes. Most of it is the Google Cloud console.

1. Deploy

Render (easiest). Click Deploy to Render above. It creates a web service and a Postgres database and generates ENCRYPTION_KEY. Leave the Google variables blank for now; enter your Google address in OWNER_EMAILS. The service starts without Google credentials so you can use the setup page.

The Blueprint uses paid Render plans (Starter web service, Basic Postgres). The free web plan sleeps when idle, which makes MCP clients time out, and free Render Postgres is deleted after 30 days.

Docker Compose (any host).

cp .env.example .env      # set BASE_URL, OWNER_EMAILS, ENCRYPTION_KEY
docker compose up -d

Put it behind HTTPS (Caddy, nginx, Cloudflare Tunnel) and set BASE_URL to the public URL. The server creates its tables on start-up.

Node directly. npm ci && npm run build && npm start with the variables from .env.example in the environment.

2. Open the setup page

Visit https://<your-host>/setup. It lists what is configured, what is missing, and the exact values for the next steps.

3. Google Cloud project

1. Create a project at console.cloud.google.com.

2. APIs & Services > Library: enable Gmail API and Google Calendar API.

3. Google Auth Platform > Branding: app name, support email, then:

   • Home page https://<your-host>, privacy https://<your-host>/privacy, terms https://<your-host>/terms (the server serves these pages).

   • Authorised domain: your host. On *.onrender.com (a public suffix) this is the full host, e.g. my-mcp.onrender.com.

4. Audience: user type External, then Publish app (In production).

   • Apps left in Testing get refresh tokens that expire after 7 days, which forces you to reconnect every mailbox weekly.

   • The app will be unverified. That is fine for your own use: Google shows a warning on consent (Advanced > Go to …) and caps unverified apps at 100 users.

5. Clients > Create client: type Web application, authorised redirect URI https://<your-host>/oauth/google/callback.

6. Copy the client ID and secret into GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET, redeploy, and reload /setup. It confirms Google accepts the credentials.

Google Workspace accounts: if a Workspace admin policy blocks unconfigured third-party apps, mark the client ID as Trusted in that domain's Admin console (Security > Access and data control > API controls > Manage Third-Party App Access > Configure new app).

4. Connect your MCP client

Claude (web, desktop and mobile)

1. Settings > Connectors > Add custom connector.

2. URL https://<your-host>/mcp. Claude detects OAuth and registers itself.

3. Click Connect and sign in with an account listed in OWNER_EMAILS.

On Team and Enterprise plans an owner may need to add the custom connector for the organisation first.

Claude Code

claude mcp add --transport http google-multi-account https://<your-host>/mcp

Then run /mcp inside Claude Code and choose the server to sign in.

Other MCP clients: any client that supports Streamable HTTP with OAuth 2.1 and dynamic client registration. If its OAuth callback is not on an allowed host, add the host to ALLOWED_REDIRECT_HOSTS.

5. Connect mailboxes

Ask your assistant: "Add my work Google account as work and make it the default." It calls add_account and returns a one-time link. Open it, choose the account, and grant both Gmail and Calendar access. Repeat per account.

If you used a built-in Gmail or Calendar connector before, consider turning it off so the assistant does not choose between two sets of similar tools.

Configuration

Tools

Every tool takes an optional account: a label, full address or domain. Omit it to use the default account.

* accepts account: "all".

Notes:

• Calendar edits never email attendees unless send_updates is set.

• Drafts can carry attachments uploaded as base64 or re-used from an existing message (attach_from). gmail_update_draft replaces the whole draft, so pass attachments again to keep them.

• Messages are limited to Gmail's 25 MB.

Troubleshooting

Development

npm install
cp .env.example .env    # fill in values
npm run dev             # runs src/index.ts with tsx
DATABASE_URL=postgres://... DATABASE_SSL=false npm test

Tests cover the OAuth flow (discovery, client registration limits, owner-only sign-in, PKCE, single-use codes, refresh rotation), first-run behaviour without Google credentials, the MCP surface, the forward allowlist, time zone handling and the MIME helpers. Google API calls are not exercised in CI.

Layout

src/
  index.ts           start-up: migrations, listen
  app.ts             Express app: OAuth endpoints, Google callback, /mcp, /setup
  setup.ts           setup checklist and configuration checks
  oauthProvider.ts   OAuth 2.1 authorization server for MCP clients
  google.ts          Google OAuth helpers
  accounts.ts        account registry, routing, encrypted token storage
  mime.ts            message parsing and MIME building
  time.ts            time zone conversion
  tools/             MCP tools (admin, gmail, calendar)

Contributions are welcome. Please open an issue first for anything larger than a small fix.

Limitations

• One owner per deployment by design. OWNER_EMAILS can list several identities, but they all see every connected mailbox.

• Personal use only as an unverified Google app. Offering it to other people would need Google's OAuth verification, including a security assessment for the Gmail scope.

• Gmail and Calendar only; no Drive, Contacts or Tasks.

Licence

MIT