Skip to main content
Glama

Octomail

Octomail is a local, multi-account Gmail MCP server that exposes several Gmail accounts side by side to an MCP client, each one addressed by an explicit alias you choose (work, personal, support, ...). There is no forwarding, no mailbox aggregation, and no shared token — every account authorizes and stores its credentials independently.

Safety

Sending exists: gmail_send_draft sends real mail. No tool composes and sends in one call — gmail_create_draft only ever creates a draft, and sending is always a separate, later step against a draft you can open and read in Gmail first. Without confirm: true, gmail_send_draft only reports what it would send — recipients, subject, attachment names and sizes — and changes nothing. With confirm: true it still refuses unless every address on the draft's To, Cc, and Bcc appears in that account's allowedRecipients in accounts.json; an account with no allowedRecipients field cannot send at all, which is the default for every account. An allowlist entry is a full address (person@example.com) or a domain (@example.com); matching is case-insensitive, subdomains are not included, and a non-ASCII recipient is refused outright rather than normalised, since a homograph domain can render identically to its Latin lookalike. If the recipient list contains anything the address extractor cannot fully account for, the send is refused rather than guessed at. gmail_create_draft still warns, but creates the draft, when a recipient isn't allowlisted — nothing leaves the account until gmail_send_draft runs, so the refusal belongs there. The OAuth token has always held the gmail.compose scope, which grants sending; the previous version of this guarantee described the tool surface, not the credential — anything holding an account's tokens could already send. gmail_get_attachment writes files into OCTOMAIL_DOWNLOAD_DIR (default ~/.octomail/attachments/<account>/) at file mode 0600 in a directory at 0700, and outbound file attachments must live inside that directory. Another way mail can leave an account is gmail_create_filter's optional forward action, which installs a standing Gmail rule — and Gmail only accepts an address you have already verified on that account, which this server has no scope to do for you. No tool ever deletes a message outright, but TRASH and SPAM are ordinary Gmail labels, and adding either one to a message — directly via gmail_apply_labels, as a standing rule via gmail_create_filter, or applied to existing mail via gmail_backfill_filter — does trash or spam it, and Gmail purges trashed and spammed mail after 30 days. That is the one label pair this server gates: adding TRASH or SPAM requires an explicit confirm: true, and without it the call is refused and nothing changes; removing them is a recovery action and is never gated. The other most destructive actions available are deleting a label or a filter, which also require an explicit confirm: true — without it they return an impact report and change nothing. Deleting a label does not delete the messages that carried it, only their categorisation. The Drive tools can create folders, upload a Gmail attachment, move or rename a file, copy a file into a folder on the same account, upload a local file, and move a file to the Drive trash; nothing on Drive is ever permanently deleted or shared, the trash step needs the file's exact current name and confirm: true (a folder also confirmFolder: true), and the only bytes a Drive tool ever uploads are a Gmail attachment already on the same account or a local file inside that account's own download directory (a copy is made by Drive itself, with no bytes passing through this server). Two Drive tools read content: drive_export_file returns the text of a Google Sheet (one tab, as CSV), a Google Doc or a Google Slides presentation (as plain text), capped at 200 KB in the result, and writes a larger export into the account's download directory under a fresh name instead of overwriting anything; drive_download_file writes any other file — a PDF, a .docx, an uploaded spreadsheet — into that directory, returns the path and never the bytes, and refuses rather than overwrite a local file. A file already named that in the target folder makes the upload, move, or copy refuse rather than overwrite it. Two tools write into a Google Sheet that already exists: sheet_append_rows only adds rows under the last one with content and never overwrites a cell, and sheet_update_cells, the one tool that overwrites cells, is limited to 50 cells per call, requires the caller to state the cells' current values (expectedValues) and refuses when they differ, changes nothing without confirm: true, and needs confirmFormulas: true on top to replace a formula. Neither adds, deletes or renames a tab, changes formatting, or shares the file. OAuth tokens are stored locally at file mode 0600. See SECURITY.md for the full policy and how to report a vulnerability.

Related MCP server: gmail-mcp

Requirements

Quickstart

npm install
npm run build
npm run setup

The setup wizard collects your OAuth client credentials, authorizes each account in the browser, verifies every configured account, and prints the config blocks you paste into your MCP client.

Starting with Claude

Once the quickstart above has run, register the server with Claude Code:

claude mcp add octomail --env OCTOMAIL_ACCOUNTS_FILE=/path/to/octomail-mcp/accounts.json -- node /path/to/octomail-mcp/dist/server.js

npm run setup -- --print-config prints this command with the real paths for your checkout, plus the equivalent blocks for Claude Desktop and Codex — see docs/clients.md for those. Then start a new Claude session and try:

  • "List my Gmail accounts" — confirms the server is wired up and shows the aliases you configured.

  • "Search work for invoices from last month" — reads mail on the work alias.

  • "Help me clean up my personal inbox" — Claude can survey the mailbox, propose labels and filters, and backfill them; give it docs/filter-playbook.md for the field-tested workflow to follow.

Claude asks before anything state-changing, and the server refuses trash, spam, and deletion actions unless the call carries an explicit confirm: true (see Safety above).

Tools

  • gmail_list_accounts

  • gmail_get_profile(account)

  • gmail_search(account, query, maxResults?)

  • gmail_search_many(accounts?, query, maxResultsPerAccount?)

  • gmail_read_message(account, messageId)

  • gmail_read_thread(account, threadId)

  • gmail_list_labels(account)

  • gmail_apply_labels(account, messageIds, addLabelNames?, removeLabelNames?, confirm?)

  • gmail_create_label(account, name, textColor?, backgroundColor?, labelListVisibility?, messageListVisibility?)

  • gmail_update_label(account, label, newName?, textColor?, backgroundColor?, labelListVisibility?, messageListVisibility?, renameDescendants?)

  • gmail_delete_label(account, label, confirm?)

  • gmail_archive(account, messageIds)

  • gmail_create_draft(account, to, subject, body, cc?, bcc?, replyToMessageId?, attachments?)

  • gmail_list_drafts(account, maxResults?)

  • gmail_get_draft(account, draftId)

  • gmail_update_draft(account, draftId, to, subject, body, cc?, bcc?, attachments?)

  • gmail_delete_draft(account, draftId, confirm?)

  • gmail_send_draft(account, draftId, confirm?)

  • gmail_get_attachment(account, messageId, attachmentId, encoding?)

  • gmail_list_filters(account)

  • gmail_create_filter(account, from?, to?, subject?, query?, negatedQuery?, hasAttachment?, excludeChats?, size?, sizeComparison?, addLabelNames?, removeLabelNames?, forward?, confirm?)

  • gmail_delete_filter(account, filterId, confirm?)

  • gmail_backfill_filter(account, filterId, apply?, maxResults?, pageToken?, confirm?)

  • calendar_list_calendars(account)

  • calendar_list_events(account, calendarId?, timeMin, timeMax, maxResults?) — returns title, time, location, and attendee count, but omits the event description (typically auto-pasted conference meeting IDs and access codes)

  • calendar_respond_to_event(account, calendarId?, eventId, response, comment?) — answers an invitation as the calling account (accepted, declined, tentative). It rewrites the responseStatus of the one attendee entry carrying this account's own address, leaves every other attendee and every other field of the event as it found them, and sends no notification mail of its own — the answer reaches the organizer's copy of the event either way. It cannot create, move, or delete an event, and it refuses a recurring series id, which would answer for every occurrence at once.

  • calendar_create_event(account, calendarId?, summary, start?, end?, startDate?, endDate?, description?, location?, attendees?, sendUpdates?) — a timed event needs start and end as RFC3339 timestamps carrying a UTC offset, because Google reads an offset-less timestamp in the calendar's own zone; an all-day event needs startDate and endDate, where endDate is exclusive. Attendees are gated on the account's allowedRecipients, the same list that gates sending, since a guest receives the invitation. sendUpdates defaults to none.

  • calendar_update_event(account, calendarId?, eventId, summary?, start?, end?, startDate?, endDate?, description?, location?, attendees?, sendUpdates?, confirmSeries?) — writes only the fields passed, except attendees, which replaces the whole guest list. The event is read first and written back under If-Match with the etag from that read, so a change made elsewhere in the meantime fails the write instead of overwriting it. A call naming no field is refused rather than sent as a no-op edit, and a recurring series id needs confirmSeries: true.

  • ical_list_feeds() — lists the subscribed iCal feeds configured under calendarFeeds in accounts.json, by alias and host. The URL itself is withheld from the result: a feed link is a bearer token for the whole calendar, and results end up in transcripts.

  • ical_list_events(feed, timeMin, timeMax, maxResults?) — reads one feed. Recurrence rules are expanded into individual occurrences, EXDATE exclusions are honoured, and an override of a single occurrence replaces that occurrence instead of appearing as a second event. Takes a feed alias, never a URL, so nothing read from a page or a message can make this server fetch an arbitrary host. Feeds are read-only by nature: an .ics subscription is a file served over HTTP and has no write protocol — to get a writable copy, mirror it into a real Google calendar.

  • calendar_delete_event(account, calendarId?, eventId, confirm?, confirmSeries?, sendUpdates?) — cannot be undone: Google Calendar keeps no trash for events. Without confirm: true it deletes nothing and returns the event it would delete, so the decision is made against the real title and time. Also guarded by If-Match, and a series id needs confirmSeries: true.

  • drive_list_files(account, folderId?, nameContains?, foldersOnly?, maxResults?, pageToken?) — lists the children of a folder (default the account's My Drive root) or searches all of Drive, including shared drives, by a name fragment; pass folderId or nameContains, not both. Read-only: it never returns file content.

  • drive_create_folder(account, name, parentId?) — creates a folder, or if one of that name already exists directly under the given parent, returns it instead with created: false and creates nothing.

  • drive_save_attachment(account, messageId, attachmentId, folderId, name?) — saves a Gmail attachment straight into a Drive folder; the bytes go directly from Gmail to Drive, never through local disk. folderId is required, and the new file's description records the source account, message id, subject, sender, and date. Refuses, naming the existing file's id, when a file with the target name already exists in that folder, rather than overwriting it. A local file goes up with drive_upload_file instead, with no draft in between.

  • drive_move_file(account, fileId, folderId?, name?) — moves a Drive file to a different folder, renames it, or both in one call, removing it from every previous parent. Refuses when a file with the resulting name already exists in the target folder. Cannot copy the file or move it to a different account.

  • drive_move_files(account, items[{fileId, folderId?, name?}]) — the batch form of drive_move_file: up to 100 rows in one call, in order, one result row per item (moved with the previous parents and name, or refused with the reason); a refused row never stops the others. Same checks as the single tool.

  • drive_copy_file(account, fileId, targetFolderId, newName?) — copies a Drive file into a folder on the same account, under newName or the source's own name. A Google Doc or Sheet copies as the same Google type, a binary file byte for byte, and a copy from My Drive into a shared drive works; Drive performs the copy, so no bytes pass through this server. The copy's description records the source file id, name, and time, appended to any description the source already carried. Refuses, naming the existing file's id, when a file with the resulting name already exists in the target folder, and refuses a folder as the source. Never modifies the source and cannot delete, move, or overwrite anything.

  • drive_trash_file(account, fileId, expectedName, confirm?, confirmFolder?) — moves one Drive file or folder to the Drive trash (files.update with trashed=true), where Drive keeps it for 30 days and it can be restored; never a permanent delete, there is no files.delete and no emptyTrash in this server. expectedName must equal the file's current name (compared after Unicode NFC normalisation, so a macOS-uploaded name with decomposed accents still matches), so a wrong or stale id is refused. The result carries the file's owners; when Drive refuses the trash because this account is not the owner, the refusal names the owner. Without confirm: true it changes nothing and returns the file it would trash; a folder additionally needs confirmFolder: true, because trashing a folder trashes its contents. Refuses a file already in the trash.

  • drive_trash_files(account, items[{fileId, expectedName}], confirm?, confirmFolder?) — the batch form of drive_trash_file for an accepted list: up to 100 rows in one call, processed in order, one result row per item with trashed, wouldTrash or refused and the reason; a refused row never stops the others. Same guards, same trash-only outcome.

  • drive_create_spreadsheet(account, name, folderId, sheets[{title, rows}], valueInput?) — creates a new Google Sheet in a folder (My Drive or a shared drive) and fills its tabs in one call: up to 20 tabs and 20 000 cells, the first tab replacing the default one. Refuses a same-named file in the folder and itself never writes into an existing spreadsheet; that is what sheet_append_rows and sheet_update_cells are for. valueInput is USER_ENTERED by default (numbers and dates parsed as when typed) or RAW (every cell literal text). Uses the Sheets API under the existing drive scope. If filling fails after the file was created, the error names the new id so it can be trashed.

  • sheet_append_rows(account, fileId, sheet, rows, valueInput?, expectedStartRow?) — appends rows under the last row with content on one tab of an existing Google Sheet (spreadsheets.values.append with INSERT_ROWS), on My Drive or a shared drive. Never overwrites a cell. sheet is the exact tab title; an unknown one is refused with the list of tabs. Up to 1000 rows and 20 000 cells per call; valueInput as in drive_create_spreadsheet, so with the default USER_ENTERED a cell starting with = becomes a formula. Formulas that name their own row need its number: with expectedStartRow the call is refused, nothing written, when the first free row is a different one. The result carries the range written (updatedRange), startRow, and the row and cell counts, never the sheet's content; when Sheets placed the rows somewhere other than column A of the first free row, a notice says so. Native Google Sheets only — an uploaded .xlsx, a PDF or a Doc is refused. Does not create, delete or rename tabs, change formatting, or share.

  • sheet_update_cells(account, fileId, sheet, range, values, expectedValues, confirm?, confirmFormulas?, valueInput?) — overwrites a small range on one tab of an existing Google Sheet; the only tool that changes existing cells. range is bounded A1 notation without a tab name (B7, B7:D9), at most 50 cells; values and expectedValues must have exactly its shape, "" for an empty cell (and "" in values clears one). expectedValues must equal what the cells show now — the formatted text drive_export_file returns — or the call is refused with each differing cell. Without confirm: true it changes nothing and returns a preview: before, after, mismatches, and the formulas in the range (formulasBefore). Replacing a formula additionally needs confirmFormulas: true. A range reaching past the tab's existing data is refused and pointed at sheet_append_rows. The result carries before, after (read back, formatted), updatedCells and changedCells. The Sheets API has no conditional write, so an edit made by someone else between the tool's read and its write is not detected. Native Google Sheets only; does not create, delete or rename tabs, change formatting, or share.

  • drive_export_file(account, fileId, sheet?) — reads a Google Sheet as CSV (one tab; sheet picks it by title, default the first) or a Google Doc or Google Slides presentation as plain text (Slides without speaker notes). Google-native documents only: any other mime type is refused before any content request. The result's text is capped at 200 KB, cut on a line boundary; when cut, truncated: true and the full text is written into OCTOMAIL_DOWNLOAD_DIR/<account> with the path in savedTo, never overwriting an existing file. Sheets are read through the Google Sheets API under the existing drive scope, so that API must be enabled on the Cloud project. A PDF, .docx or other file with bytes of its own is refused here and pointed at drive_download_file.

  • drive_upload_file(account, filePath, folderId, name?, convertToGoogleDoc?, description?) — uploads a local file into a Drive folder, My Drive or a shared drive. filePath must resolve inside OCTOMAIL_DOWNLOAD_DIR/<account> (relative paths resolve against it), the same rule gmail_create_draft applies to attachments: an absolute path elsewhere, a .. traversal, a symlink pointing out, or another account's directory is refused before any network call. Up to 5 MB, the limit of the single-request upload the Google client library sends. With convertToGoogleDoc: true, a .docx, .doc, .odt, .rtf or .txt becomes a Google Doc and an .xlsx, .xls, .ods or .csv a Google Sheet, named without the extension unless name is given; any other format is refused. Refuses, naming the existing file's id, when a file with the resulting name already exists in the folder. Returns the Drive file (id, name, mimeType, sizeBytes, parents, webViewLink, md5Checksum) and the source path, size and type.

  • drive_download_file(account, fileId, outDir?, name?, maxBytes?) — downloads a file that has bytes of its own (PDF, .docx, .xlsx, image, archive) into OCTOMAIL_DOWNLOAD_DIR/<account>, or an outDir inside it (created if missing; a path outside is refused), under name or the Drive name with unsafe characters replaced. Returns the path as savedTo and never the content. A Google Doc, Sheet or other Google-native file, and a folder, are refused with a pointer to drive_export_file. A file over maxBytes (default 100 MB) is refused before any content is fetched. The bytes are checked against Drive's reported size and md5 before anything is written, and both are returned with verified (true, or "unavailable" when Drive reports no value); a mismatch writes nothing. Refuses when a local file of that name already exists, and never overwrites one. Read-only on Drive.

Documentation

Guide

Covers

docs/google-cloud-setup.md

Creating the Google Cloud project, OAuth consent screen, and the 7-day token expiry to avoid

docs/accounts.md

Aliases, accounts.json, adding/removing accounts, checking account health

docs/clients.md

Wiring the server into Claude Code, Claude Desktop, and Codex

docs/troubleshooting.md

Fixes for common authorization and config errors

docs/filter-playbook.md

Field-tested workflow and lessons for cleaning up a mailbox with filters, backfills, and verification

CONTRIBUTING.md

The no-real-user-data rule for code, tests and docs, and the 2026-09-14 history rewrite

Commands

Command

What it does

npm run setup

Interactive wizard: collects OAuth credentials, authorizes accounts, verifies them, prints client config

npm run auth -- --account <alias>

Authorizes (or re-authorizes) one account by alias

npm run doctor

Checks environment, build freshness, and every configured account; exits 1 on failure

npm run build

Compiles TypeScript to dist/

npm run dev

Runs the server directly from source with tsx

npm test

Runs the test suite

Notes

  • gmail_apply_labels accepts label display names or Gmail label IDs.

  • gmail_search_many searches all configured accounts when accounts is omitted, and returns per-account errors without hiding successful results from other accounts.

  • gmail_archive only removes the INBOX label.

  • gmail_create_draft and gmail_update_draft create or replace a draft only; gmail_send_draft is the one tool that transmits mail, and it is gated as described in Safety above.

  • Unknown account aliases and missing token files return readable errors.

License

Apache-2.0. Copyright 2026 Zero Story Points.

Available Tools

41 tools
calendar_create_eventA

Create an event on one Google Calendar. Timed events need start and end as RFC3339 timestamps carrying a UTC offset; all-day events need startDate and endDate, where endDate is exclusive. Guests are only accepted if they are on the account's allowedRecipients, and no notification mail is sent unless sendUpdates is "all".

Inputs: account (required), summary (required), end, start, +7 more.

calendar_delete_eventA

Delete an event. THIS CANNOT BE UNDONE — Google Calendar keeps no trash for events. Without confirm: true it changes nothing and returns the event it would delete, so the decision is made against the real title and time. A recurring series id is refused unless confirmSeries is true.

Inputs: account (required), eventId (required), confirm, calendarId, +2 more.

calendar_list_calendarsA

List the Google Calendars an account can read.

Inputs: account (required).

calendar_list_eventsA

List events from one Google Calendar within a time range. Recurring events are expanded into individual occurrences. Read-only.

Inputs: account (required), timeMax (required), timeMin (required), calendarId, +1 more.

calendar_respond_to_eventA

Answer a calendar invitation on behalf of the calling account: accept, decline, or answer tentatively, with an optional comment to the organizer. Changes only this account's own participation status — it cannot create, move, or delete an event, or change anyone else's answer.

Inputs: account (required), eventId (required), response (required), comment, +1 more.

calendar_update_eventA

Change fields of an existing event: title, description, location, guests, or its start and end. Only the fields passed are written, except attendees, which replaces the whole guest list. Guarded with the event's etag, so a change made elsewhere in the meantime fails the write instead of overwriting it. A recurring series id is refused unless confirmSeries is true.

Inputs: account (required), eventId (required), end, start, +9 more.

drive_copy_fileA

Copy a Google Drive file into a folder on the same account, optionally under a new name. Drive performs the copy on its side, so no bytes pass through this server; a Google Doc or Sheet copies as the same Google type, a PDF or image byte for byte, and a copy from My Drive into a shared drive works. The copy's description records the source file and time, appended to any description the source already had. Refuses when a file with the resulting name already exists in the target folder rather than overwriting it, and refuses a folder as the source. Only copies: it cannot delete, move, rename, share, or overwrite anything, and it never modifies the source.

Inputs: fileId (required), account (required), targetFolderId (required), newName.

drive_create_folderA

Create a folder in Google Drive. If a folder with the same name already exists directly under the given parent, that folder is returned instead of creating a duplicate. Cannot rename, move, delete, upload into, or share the folder it creates or finds.

Inputs: name (required), account (required), parentId.

drive_create_spreadsheetA

Create a new Google Sheet in a Drive folder (My Drive or a shared drive) and fill its tabs in one call: name, folderId, and sheets as [{title, rows: string[][]}], up to 20 tabs and 20 000 cells. Refuses when a file with that name already exists in the folder; never writes into an existing spreadsheet, never shares. Values are written as USER_ENTERED by default (numbers and dates are parsed as a person typing them would get); pass valueInput: "RAW" to store every cell as literal text.

Inputs: name (required), sheets (required), account (required), folderId (required), +1 more.

drive_export_fileA

Read the content of a Google-native document on Drive: a Google Sheet as CSV (one tab, default the first; pass sheet to pick another by title) or a Google Doc as plain text. Read-only and never a binary file: a PDF, image, or uploaded .xlsx is refused. The text in the result is capped at 200 KB; a larger export is truncated on a line boundary, and the full text is written into the account's download directory (OCTOMAIL_DOWNLOAD_DIR/) with its path returned as savedTo.

Inputs: fileId (required), account (required), sheet.

drive_list_filesA

List files and folders in a Google Drive folder, or search all of Drive by a name fragment. Read-only: it never opens, downloads, or reveals file content, only metadata (name, type, size, modified time, parent folders, link, checksum). Pass folderId or nameContains, not both.

Inputs: account (required), folderId, pageToken, maxResults, +2 more.

drive_move_fileA

Move a Google Drive file to a different folder, rename it, or both in one call. Refuses when a file with the resulting name already exists in the target folder. Cannot delete or copy the file, and cannot move it to a different Google account.

Inputs: fileId (required), account (required), name, folderId.

drive_move_filesA

Batch form of drive_move_file: up to 100 {fileId, folderId?, name?} rows in one call, processed in order, one result row per item with the same checks as the single tool (a name collision in the target folder, a missing target, a trashed source each refuse that row only; the others proceed). Cannot delete, copy, or move to another account.

Inputs: items (required), account (required).

drive_save_attachmentA

Save a Gmail attachment straight into a Google Drive folder — the bytes go directly from Gmail to Drive, never through local disk and never back in the tool result. Refuses when a file with the target name already exists in that folder rather than overwriting it. Cannot delete anything, and cannot upload a local file: only an attachment already on a Gmail message.

Inputs: account (required), folderId (required), messageId (required), attachmentId (required), +1 more.

drive_trash_fileA

Move one Google Drive file or folder to the Drive trash (files.update with trashed=true), where Drive keeps it for 30 days and it can be restored. Never a permanent delete: this server has no files.delete and no emptyTrash. Two guards: expectedName must equal the file's current name exactly, so a wrong or stale id is refused; and without confirm: true the call changes nothing and returns the file it would trash. A folder additionally needs confirmFolder: true, because trashing a folder trashes its contents. Refuses a file that is already in the trash.

Inputs: fileId (required), account (required), expectedName (required), confirm, +1 more.

drive_trash_filesA

Batch form of drive_trash_file for an accepted list: up to 100 {fileId, expectedName} items in one call, processed in order, one result row per item; a refused row (name mismatch, already in the trash, not found, no permission) never stops the others. Same guards as the single tool: expectedName must equal each file's current name, confirm: true is required to trash and without it the call only previews, and a folder needs confirmFolder: true. Trash only, restorable for 30 days; no permanent delete exists in this server.

Inputs: items (required), account (required), confirm, confirmFolder.

gmail_apply_labelsA

Add and/or remove labels on Gmail messages. Label names may also be Gmail label IDs. Adding TRASH or SPAM destroys mail after Gmail's 30-day purge, so that requires confirm: true; removing them does not.

Inputs: account (required), messageIds (required), confirm, addLabelNames, +1 more.

gmail_archiveA

Archive Gmail messages by removing the INBOX label.

Inputs: account (required), messageIds (required).

gmail_backfill_filterA

Apply an existing filter's labels to mail already in the mailbox. Dry run by default: reports what would change and modifies nothing until apply is true. The filter's forward action is deliberately ignored. If the filter adds TRASH or SPAM, applying it destroys mail after Gmail's 30-day purge, so apply: true additionally requires confirm: true — the dry run itself is never gated.

Inputs: account (required), filterId (required), apply, confirm, +2 more.

gmail_create_draftA

Create a Gmail draft. This tool does not send: use gmail_send_draft, which is gated on the account's allowedRecipients list.

Inputs: to (required), body (required), account (required), subject (required), +4 more.

gmail_create_filterA

Create a Gmail filter. Filters only affect mail that arrives after they are created — use gmail_backfill_filter for existing mail. Gmail allows at most one user-defined label per filter. Adding TRASH or SPAM installs a standing rule that destroys future matching mail after Gmail's 30-day purge, so that requires confirm: true; removing them does not.

Inputs: account (required), to, from, size, +10 more.

gmail_create_labelA

Create a Gmail label. Nest it by using a path name such as "Clients/Acme".

Inputs: name (required), account (required), textColor, backgroundColor, +2 more.

gmail_delete_draftA

Permanently delete a Gmail draft. Requires confirm: true — a deleted draft does not go to Trash and cannot be recovered.

Inputs: account (required), draftId (required), confirm.

gmail_delete_filterA

Delete a Gmail filter. Without confirm: true this only reports the filter's full definition and changes nothing. The Gmail API has no filter update — edit by deleting and recreating.

Inputs: account (required), filterId (required), confirm.

gmail_delete_labelA

Delete a Gmail label. Without confirm: true this only reports what would be lost and changes nothing. Deleting a label does not delete messages, but their categorisation is lost permanently.

Inputs: label (required), account (required), confirm.

gmail_get_attachmentA

Fetch one attachment from a Gmail message. Writes it into the account's download directory and returns the path (encoding: file, the default), or returns the bytes inline as base64 (encoding: base64, capped at 750 KB). Attachment ids come from the attachments array on gmail_read_message.

Inputs: account (required), messageId (required), attachmentId (required), encoding.

gmail_get_draftA

Read one Gmail draft. Its output feeds directly back into gmail_update_draft.

Inputs: account (required), draftId (required).

gmail_get_profileC

Get Gmail profile for an account.

Inputs: account (required).

gmail_list_accountsA

List configured Gmail account aliases, with their email address and whether they are authorized.

Inputs: no named parameters.

gmail_list_draftsA

List Gmail drafts on one account, newest first. Results do not include attachment info (fetched with format: metadata, which never populates the MIME parts tree) — use gmail_get_draft on a specific draft to see its attachments.

Inputs: account (required), maxResults.

gmail_list_filtersA

List Gmail filters for an account, with each filter's criteria rendered as the equivalent search query.

Inputs: account (required).

gmail_list_labelsB

List Gmail labels for an account.

Inputs: account (required).

gmail_read_messageB

Read one Gmail message.

Inputs: account (required), messageId (required).

gmail_read_threadB

Read one Gmail thread.

Inputs: account (required), threadId (required).

gmail_search_manyA

Search Gmail messages across multiple configured accounts. Results are grouped by account. Results do not include attachment info (fetched with format: metadata, which never populates the MIME parts tree) — use gmail_read_message on a specific message to see its attachments.

Inputs: query (required), accounts, maxResultsPerAccount.

gmail_send_draftA

Send an existing Gmail draft. THIS SENDS REAL MAIL. Requires confirm: true, and every recipient on the draft's To, Cc and Bcc must be on the account's allowedRecipients list in accounts.json — an account with no such list cannot send at all. Without confirm, returns what would be sent and changes nothing.

Inputs: account (required), draftId (required), confirm.

gmail_update_draftA

Replace the contents of a Gmail draft. Gmail has no partial draft update: this replaces the whole message, so ANY ATTACHMENT NOT RE-SPECIFIED IS DROPPED. To keep an existing attachment, pass {messageId: , attachmentId: ...}.

Inputs: to (required), body (required), account (required), draftId (required), +4 more.

gmail_update_labelA

Rename and/or restyle a Gmail label. Gmail stores hierarchy in the name, so renaming a parent does not rename its children unless renameDescendants is true.

Inputs: label (required), account (required), newName, textColor, +4 more.

ical_list_eventsA

Read events from one subscribed iCal feed within a time range. Recurring rules are expanded into individual occurrences, and overrides of single occurrences are applied. Read-only: an .ics feed cannot be written to. Takes a feed alias from accounts.json, never a URL — so nothing read from a page or a message can make this server fetch an arbitrary host.

Inputs: feed (required), timeMax (required), timeMin (required), maxResults.

ical_list_feedsA

List the subscribed iCal feeds configured in accounts.json under "calendarFeeds". Feeds are read-only by nature: an .ics subscription is a file served over HTTP and has no write protocol.

Inputs: no named parameters.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 41 tools

    Disambiguation4/5

    Tools are clearly grouped by service and action, so most names map to a distinct purpose. The closest overlap pairs are gmail_search vs gmail_search_many and the single/batch Drive variants, but their descriptions and signatures disambiguate them well.

    Naming Consistency4/5

    Names consistently use snake_case with service prefixes like gmail_, calendar_, ical_, and drive_, and mostly follow the verb_noun pattern. Minor inconsistencies such as gmail_get_profile and gmail_get_draft versus gmail_read_message and gmail_read_thread keep it from being a perfect 5.

    Tool Count2/5

    41 tools is well over the 25-tool threshold useful for a coherent single tool set, and the count is inflated by single/batch pairs like drive_move_file/drive_move_files and drive_trash_file/drive_trash_files. The breadth is partly justified by spanning Gmail, Calendar, iCal, and Drive, but the surface is still heavy and over-factored.

    Completeness4/5

    Core workflows are well covered: Gmail search/read/drafts/labels/filters/send, calendar CRUD and response, iCal reading, and Drive move/copy/trash/export with Gmail-to-Drive attachment saving. Gaps like direct upload, permanent Drive delete, replies, and sharing are documented or explicitly excluded, so agents can work around them.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Connect multiple Gmail accounts to any MCP client, enabling search, read, draft, send, label, and organize mail across unlimited accounts with local-only OAuth token storage.
      22
      17 npm
      9
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables interacting with multiple Gmail accounts through a single MCP server, supporting search, labels, drafts, and thread management with per-account OAuth.
      1
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      Multi-account Gmail MCP server for reading threads, managing labels, and creating drafts across multiple Gmail accounts.
      -