Grounders MCP

Hub — a multi-account Google connector for Claude

A remote MCP server that gives Claude access to several Google accounts at once — Gmail, Calendar, Drive, Contacts and Tasks. Claude's built-in Google connectors each hold exactly one account; connecting a second replaces the first. This holds as many as you link, and every search tool fans out across all of them in a single call.

AOL mailboxes link too. They are reached over IMAP and SMTP with an app password, sit behind the same mail tools, and are searched together with Gmail — see AOL mailboxes.

Run it yourself and it holds your Google tokens in your own database, encrypted, and talks to Google directly — nothing passes through a third party. Or try the hosted one first.

Node and Postgres, six tables. Dependencies are Express, pg and jsonwebtoken, plus imapflow, mailparser and nodemailer for AOL — IMAP, MIME and SMTP are protocols, not parsing jobs, and each library is the maintained standard for its one. Document text extraction — PDF, Word, Excel, PowerPoint, OpenDocument — uses only Node's standard library.

Status: running in production against real mailboxes, with 564 automated checks. Built for one person's needs and published because the one-account limit is not unique to them. Treat it as working software with a small user base, not as a hardened product.

Try the hosted one

A copy runs at hub.grounders.app. It is in testing, and free while it is.

1. In Claude: Settings → Connectors → Add custom connector, with the URL https://hub.grounders.app/mcp. ChatGPT, Cursor and other MCP clients take the same URL as a remote MCP server.
2. Sign in with Google once when asked.
3. Link each account at hub.grounders.app/gmail/connect.

Google's review of the app is still in progress, so you will see an "unverified app" screen the first time.

Quick start

git clone https://github.com/ItsBreeze/google-multi-account-mcp.git
cd google-multi-account-mcp
npm install
cp .env.example .env      # fill it in — see Setup below
npm run migrate           # creates the six tables
npm start

Then deploy it somewhere with a public HTTPS URL (Railway, Fly, Render, a VPS — anything that runs Node and reaches Postgres) and follow Setup.

Endpoints

Tools (59)

Every tool takes an optional account. On a search, omitting it fans the call out across every linked account and merges the results — the thing no single-account connector can do. On a write it names the one account to act on, so "create this event" is never ambiguous about whose calendar it lands in.

Mail — Gmail and AOL (23)

Calendar (9)

Drive (15)

Contacts (2) and Tasks (5)

AI agents (5)

AIs talk to each other through Hub instead of by email. Every message has a thread, a hop count and a read time, so nothing is lost to subject matching and a sender can see whether it was read.

An agent without MCP needs no account: each wake carries a signed reply_url (30 days, one owner, one agent). POST {"text":"..."} to it to answer, GET it to read the thread, or POST {"new_thread":true,"to":"claude","text":"..."} to start a new conversation.

AOL mailboxes

Link one at /gmail/aol with the address and an app password generated at AOL Account Security — AOL has no OAuth for third-party mail clients outside an approved partner list, so this is the only door. The password is signed in to IMAP before it is stored (one app password covers IMAP and SMTP), so a typo is reported on the link page, not on Claude's first tool call. It is stored AES-256-GCM encrypted under TOKEN_ENC_KEY, like the Google tokens. Hosts come from a preset in code (imap_providers.js), never from the request.

Sending goes through a relay where SMTP is blocked. Railway blocks outbound SMTP below its Pro plan, so hub.grounders.app hands each AOL submission over HTTPS to a Cloudflare Worker (smtp-relay/) that speaks SMTP to smtp.aol.com:465. The Worker stores and logs nothing and reaches only preset hosts. It is used when SMTP_RELAY_URL and SMTP_RELAY_TOKEN are set; without them the server talks SMTP directly, as a self-hosted copy that can reach port 465 should. Gmail sending is unaffected — it goes through Google's API.

The 23 mail tools work on an AOL mailbox unchanged, and a search with no account covers Gmail and AOL in one merged, date-sorted result. What differs is IMAP itself, and the tools say so rather than pretend:

No permanent delete, enforced in code. Gmail's guarantee is structural — the scope cannot expunge. An app password can do anything, so here it is a property of imap_api.js: its one expunge is removeDraft, which acts on a single UID in the Drafts folder by UID EXPUNGE (and sends the draft to Trash on a server without it, since plain EXPUNGE would take every other \Deleted message too). Moves refuse a server that would emulate MOVE with a mailbox-wide expunge. npm run test:imap drives the client against a scripted server and asserts every expunge it ever sees was one draft, in Drafts.

Document text extraction

read_file_content and get_attachment both return text for PDF, Word, Excel, PowerPoint and OpenDocument files, using only Node's standard library — no parsing dependency to vendor, audit or keep current.

Where it stops, and what happens then. Two kinds of PDF have no text to extract: a scan, which is a picture of a page, and one whose fonts are CID-keyed or subset, where the bytes in the content stream are glyph numbers that need the font's own tables to become letters. Both would decode into confident-looking nonsense, so the result is scored for readability and refused rather than returned — the refusal names the cause and points at the fix.

That fix is ocr: true on read_file_content, which copies the file as a Google Doc (Drive runs OCR during that conversion), exports the text, and deletes the copy in a finally block. It reads scans, photographs and images. Two things worth knowing: it is the one place this server writes to Drive during a read, and that delete is the only permanent delete in the whole server — its target is a file created seconds earlier by that same call, never anything the user put there. If the cleanup itself fails, the result says so and names the file.

Extraction is capped at 60 KB like every other body, with the cut flagged.

Shared drives

A shared drive is owned by an organisation rather than by a person, which is where a company's actual documents live. Drive's own default hides them: a files.list without corpora=allDrives searches only My Drive and files shared directly with the account, and a request naming a file inside a shared drive comes back 404 File not found unless it carries supportsAllDrives — an error that reads as a wrong id rather than as a missing capability.

Every Drive request that accepts that parameter now carries it, applied in one place rather than at each of the eighteen call sites, so the next endpoint added cannot quietly reintroduce the gap. Which methods accept it is not a guess: it is taken from the v3 discovery document, and files.export, comments and replies are deliberately left out because they do not take it.

Searches therefore span My Drive and every shared drive by default, and results name the drive a file came from rather than just its id. Google recommends narrowing where you can, so list_shared_drives gives the ids and drive_id confines a search to one.

This widens what writes can reach as well as reads: a file in a shared drive was previously unreachable by update_file, share_file or trash_file, and now is. Since a shared drive holds an organisation's documents rather than one person's, that is exactly the case the ownership rule below exists for.

A drive is named where it can be, and says so where it cannot. drives.list covers the drives this account is a member of, paged rather than cut off at Drive's hundred-per-call — an account in more drives than that would otherwise have the overflow look like non-membership.

A file can also reach you from a drive you are not in, through a folder shared directly. Such a drive cannot be named at all. Its id is also its root folder's id, but reaching a file inside a drive grants nothing on the root folder above it, so asking answers File not found — verified against a real Workspace account, where two of three drives holding recent files were reached this way. Those carry shared_drive_member: false rather than a bare id, so "no name available" is distinguishable from "lookup failed".

Writes land on files you own

A file owned by someone else — or by an organisation, which is every file in a shared drive, including ones you created there — is not this connector's to change on a model's judgement.

The draft is the point. It states each field as from → to, and for a content replacement it reads what is there now and shows the lines that actually change — not just "this will overwrite 40 KB". Binary content says a preview is impossible rather than faking one. Nothing is written until a second call arrives, so a person sees the specific change before it lands rather than being told afterwards which of their colleague's documents moved.

The private copy names parents: ['root'] deliberately: files.copy with no parent puts the copy beside the source, which for a shared-drive file would leave it in that same shared drive — still not private.

share_file and trash_file draft too, but have no copy path: copying a colleague's document and sharing that spreads their content further, not less.

Revoking and restoring are never gated. unshare_file and untrash_file work without confirmation on any file, yours or not. Widening access needs approval; narrowing never does. A brake that needs permission is not a brake.

Repeating events

list_events expands a series into its occurrences — "what's on Tuesday" means the standup that Tuesday, not the rule that generates it. The consequence is that the id in hand is almost always one occurrence, and Google offers no flag saying whether an edit was meant for that occurrence or for all of them.

So update_event and delete_event take a scope:

Reads carry recurring_event_id, which is what makes that resolution possible at all, and the result of every write says which it actually did. That matters in one direction especially: an id naming the series itself changes every occurrence even under this_event, because that is what patching a series does — so the result says applies_to: "series" rather than letting it pass silently.

Creating a repeating event takes repeat: "daily" | "weekly" | "monthly" | "yearly", with repeat_count or repeat_until to end it. Anything those cannot say — every second Tuesday, weekdays only — goes in recurrence as RFC 5545 lines. Those are checked here rather than at Google: a rule with no FREQ, an unknown frequency, or a DTSTART line all come back naming the problem, where Google answers a generic 400. A repeat rule belongs to a series and is silently dropped if written to one occurrence, so that is refused too.

Setup

1. Google Cloud — create a project; enable the Gmail, Calendar, Drive, People and Tasks APIs; configure the consent screen as External, and add every Google address you plan to link as a test user. Create an OAuth client of type Web application with the authorized redirect URI set to exactly <PUBLIC_BASE_URL>/gmail/oauth/callback.
2. Env — set DATABASE_URL, PUBLIC_BASE_URL, GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, TOKEN_ENC_KEY and JWT_SECRET (see .env.example), then deploy. The schema applies itself on boot.
3. Link accounts — visit <PUBLIC_BASE_URL>/gmail/connect, sign in with Google, then link each account once. The account you sign in with and the accounts you link are independent; sign in as yourself and link whichever mailboxes you like beneath that identity.
4. Add to Claude — Settings → Connectors → Add custom connector → <PUBLIC_BASE_URL>/mcp. Claude registers itself and sends you to the consent screen, where you sign in with Google once.

Who sees what

Every mailbox is stored against the identity that linked it, and every MCP token carries that identity as its subject — through refreshes as well as the first grant. Two people using the same deployment reach only their own accounts, and naming somebody else's address in a tool call is refused rather than served. npm run test:isolation asserts exactly that.

Upgrading from the single-operator build, where every token carried the same subject: set LEGACY_OWNER_EMAIL to the address those mailboxes belong to, and the first sign-in from that address adopts them. Nothing needs re-linking. Unset it afterwards.

If you linked accounts before adding a product: the granted scopes are fixed at link time, so an account linked before Calendar, Drive, Contacts and Tasks existed holds a Gmail-only grant. Google will not extend it retroactively. Visit /gmail/connect again for each account — that adds the missing access and changes nothing else. Until then the new tools name the account and say to re-link it, rather than failing with an opaque 403.

Deploying

Any host that runs Node and reaches Postgres works. There is nothing to build, no container to define, and the schema applies itself on boot — a fresh deployment needs only environment variables.

Environment

/gmail/check diagnoses a bad Google client without running the whole consent round-trip, and reports which of the two variables Google rejected. Values are never echoed back.

On Railway

Create a project from this repository and add a Postgres service, which provides DATABASE_URL for the app service to reference. Set the rest above, take the generated domain as PUBLIC_BASE_URL, and register <PUBLIC_BASE_URL>/gmail/oauth/callback as an authorized redirect URI on the OAuth client. Pushes to the default branch redeploy automatically.

Moving an existing deployment

Two facts make this a cutover rather than a migration, with no downtime and no re-linking:

• Point the new deployment at the same database. The schema is CREATE TABLE IF NOT EXISTS, so it is a no-op against tables that already exist, and every linked account carries over untouched.
• Carry TOKEN_ENC_KEY across unchanged. Tokens are AES-256-GCM, which is authenticated: a different key fails the tag check and throws rather than returning nonsense, so the failure is loud — but every account is unusable until the original key is restored.

An OAuth client accepts several redirect URIs, so add the new deployment's callback rather than replacing the old one. Both deployments can then run side by side against the same database — nothing else writes those five tables — which leaves room to verify the new one before retiring the old.

Expect Claude to authenticate once more afterwards if JWT_SECRET changed. Linked Google accounts survive it: they are keyed to a constant subject, not to any particular token.

Security notes

• Google refresh and access tokens are AES-256-GCM encrypted at rest under TOKEN_ENC_KEY. The database never holds a usable token.
• Mail cannot be permanently deleted. The Gmail scope is gmail.modify: read, send, label, archive, trash. It deliberately excludes mail.google.com, so trash_message is recoverable for 30 days and nothing here can destroy mail.
• Drive is different, and the difference is worth knowing. Drive has no equivalent middle scope: drive.file only sees files this app itself created, which cannot answer "find my lease", so searching and editing existing files needs full drive — which does permit permanent deletion. There the limit is enforced by the tool surface instead: trash_file trashes, and no tool reaches Drive's permanent-delete endpoint. That is a weaker guarantee than Gmail's, because it is a matter of what is exposed rather than what is possible.
• Every outward action has an undo, which is the condition for offering it. unshare_file withdraws any grant share_file can make, and untrash_file restores what trash_file removed. The first-party connector has neither, so a permission it grants cannot be taken back through the same interface. This is the one place the wider surface here is also the safer one.
• AOL app passwords are the one stored credential that is not an OAuth grant. They are encrypted like the tokens, checked before storage, never logged (both protocol clients run with logging off), and cannot be revoked from here — unlinking deletes the stored copy, and the link and deletion pages say to delete the app password at AOL too. The link form is behind the sign-in rate limit, so it cannot be used to guess AOL passwords through this server.
• Contacts are read-only by scope, not just by omission.
• Drive writes are guarded where the first-party connector is simply narrower. Claude's Drive connector shares with one email address and a role — it has no way to publish a file — and its update_file changes only the title and parent. Two guards match that default, because both failures are one-way and neither looks alarming in a tool result:
  • share_file takes a named person only. Domain-wide and public-link sharing need DRIVE_ALLOW_PUBLIC_SHARING=true, and are refused outright otherwise rather than quietly narrowed to something safer. Even enabled, they need confirm_public: true as a second signal, and the refusal spells out what the grant would actually mean before it is repeated.
  • Overwriting a file's contents needs alongside , so a rename can never destroy a document as a side effect.

Architecture

src/services/google_http.js     shared transport: URL building, bearer auth,
                                error unwrapping, bounded-concurrency mapLimit
src/services/gmail_api.js       one thin client per Google API, each returning
src/services/calendar_api.js    shaped results rather than raw payloads
src/services/drive_api.js
src/services/people_api.js
src/services/tasks_api.js
src/services/office_text.js     .docx/.xlsx/.pptx/.odt text, via a ZIP reader
src/services/pdf_text.js        PDF content-stream text, with a readability guard
src/services/text_extract.js    one entry point both Drive and Gmail read through
src/services/gmail_accounts.js  linked accounts, token refresh, scope gating
src/services/imap_api.js        AOL over IMAP/SMTP, the same surface as gmail_api
src/services/imap_query.js      Gmail search syntax → IMAP SEARCH, refusing what it can't map
src/services/imap_accounts.js   linked AOL mailboxes, app passwords encrypted at rest
src/services/imap_providers.js  host presets — the only place a mail host comes from
src/mcp/shared.js               resolveAccount / tokenFor / fanOut / mergeSearch, and
                                mailFor / fanOutMail, which pick Gmail or IMAP per mailbox
src/mcp/tools/                  one module per product, assembled by index.js

Rate limits are respected rather than discovered: Google meters quota per user per second, so per-item detail fetches run five at a time, and a fetch that fails anyway is counted in unavailable_* rather than silently dropped from the results.

Tests

All plain Node — no framework. 564 checks.

# No database, no network:
npm run test:tokens     # MCP and user tokens cannot be swapped, in either direction
npm run test:query      # Google query-string construction (repeated array params)
npm run test:mime       # entity decoding, body truncation, MIME construction
npm run test:threads    # address parsing, thread summaries, cross-account fan-out
npm run test:products   # free-slot arithmetic, Drive query quoting, multipart
                        # upload framing, task dates, scope gating, tool-surface shape
npm run test:drive-safety   # the sharing and overwrite guards, both env states
npm run test:extract    # PDF and Office text extraction, against real fixtures
npm run test:drive-parity   # upload framing, conversion, export and comments, on the wire
npm run test:reach      # shared-drive request parameters, recurrence rules, and which
                        # event a scoped write actually lands on
npm run test:ownership  # which file id a write reaches, that a draft writes nothing,
                        # and that revoking is never gated
npm run test:imap       # AOL: query translation, and the client against a scripted
                        # IMAP/SMTP server — moves, ids, Bcc, Sent copies, no expunge
npm run test:isolation  # one person's mailboxes, Gmail or AOL, are unreachable by another
npm run test:ai         # AI messages on in-memory Postgres: threads, wakes, reply links, hops

# Needs a database:
DATABASE_URL=postgres://…  npm run test:accounts        # resolution + encryption at rest
DATABASE_URL=postgres://…  npm run test:imap-accounts   # AOL app passwords at rest, owner scoping

# Needs the API running:
npm start &
TEST_BASE_URL=http://127.0.0.1:3000  npm run test:mcp   # OAuth + MCP protocol

Mounting it inside an existing app

src/app.js is the whole standalone server and contains nothing but the connector, so embedding it is a copy of that file's body: require the two routers (routes/mcp, routes/gmail_link), keep the rate limits and the four .well-known discovery routes, and run the migration alongside your own.

One thing not to skip: MCP tokens are signed with a key derived from JWT_SECRET by HMAC rather than with JWT_SECRET itself. If your app signs its own user tokens with that secret and verifies them without an audience check, sharing the key would make every connector token a valid user token for your app. npm run test:tokens asserts the separation in both directions.

Contributing

Issues and pull requests are welcome. Two conventions worth knowing first:

• Suites are plain Node — no framework, no new dependencies. Each is a file under test/ with an npm run test:<name> script, one line per check, and a non-zero exit on failure.
• Tests assert on what goes over the wire. They stub global.fetch and check the query parameters, the request path, the multipart framing. The failures worth catching here are calls that succeed while asking the wrong question, and only a wire-level assertion sees those.

PROJECT-LOG.md records why things are the way they are, including the alternatives that were rejected. Read it before changing a decision.

License

MIT — see LICENSE.