Octomail
Octomail is a local multi-account Gmail, Calendar, and Drive MCP server for reading, organizing, drafting, sending gated mail, managing filters and calendars, and working with Drive/Sheets files.
List configured Gmail accounts and profiles, and search/read messages and threads on one or many accounts.
Manage Gmail labels, archive messages, and apply labels; adding TRASH/SPAM or deleting labels/filters requires explicit confirmation.
Create, list, read, update, and delete drafts; fetch attachments to the account download directory or inline as base64.
Send existing drafts only with
confirm: trueand only to recipients allowed by the account'sallowedRecipientsallowlist.List, create, and delete Gmail filters, and backfill filter labels onto existing mail with dry-run and confirmation controls.
List calendars/events, respond to invitations, and create, update, or delete events with confirmation, etag, and recurring-series guards.
List subscribed iCal feeds by alias and read/expand their events read-only.
Browse/search Drive files and folders, create folders, save Gmail attachments to Drive, move/rename/copy files, trash files or folders restorably, upload local files from the account download directory, download binary files with verification, and export Google-native docs/Sheets/Slides.
Create spreadsheets with tabs and rows, append rows to existing Sheets, and update limited cell ranges with expected-value and confirmation safeguards.
Most destructive actions are gated; Drive has no permanent delete, and Gmail/Drive trash or spam outcomes are documented and guarded.
Provides tools for managing Gmail accounts, including searching and reading messages, creating and sending drafts, applying labels, managing filters, and downloading attachments.
Provides tools for interacting with Google Calendar, including listing calendars and events, responding to invitations, and creating or updating events.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Octomail search my work Gmail for unread emails about the quarterly report"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
Node 20 or newer
A Google Cloud project with the Gmail API enabled (see docs/google-cloud-setup.md)
Quickstart
npm install
npm run build
npm run setupThe 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.jsnpm 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
workalias."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_accountsgmail_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 theresponseStatusof 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 needsstartandendas RFC3339 timestamps carrying a UTC offset, because Google reads an offset-less timestamp in the calendar's own zone; an all-day event needsstartDateandendDate, whereendDateis exclusive. Attendees are gated on the account'sallowedRecipients, the same list that gates sending, since a guest receives the invitation.sendUpdatesdefaults tonone.calendar_update_event(account, calendarId?, eventId, summary?, start?, end?, startDate?, endDate?, description?, location?, attendees?, sendUpdates?, confirmSeries?)— writes only the fields passed, exceptattendees, which replaces the whole guest list. The event is read first and written back underIf-Matchwith 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 needsconfirmSeries: true.ical_list_feeds()— lists the subscribed iCal feeds configured undercalendarFeedsinaccounts.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,EXDATEexclusions 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.icssubscription 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. Withoutconfirm: trueit deletes nothing and returns the event it would delete, so the decision is made against the real title and time. Also guarded byIf-Match, and a series id needsconfirmSeries: 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; passfolderIdornameContains, 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 withcreated: falseand 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.folderIdis 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 withdrive_upload_fileinstead, 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 ofdrive_move_file: up to 100 rows in one call, in order, one result row per item (movedwith the previous parents and name, orrefusedwith 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, undernewNameor 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.updatewithtrashed=true), where Drive keeps it for 30 days and it can be restored; never a permanent delete, there is nofiles.deleteand noemptyTrashin this server.expectedNamemust 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'sowners; when Drive refuses the trash because this account is not the owner, the refusal names the owner. Withoutconfirm: trueit changes nothing and returns the file it would trash; a folder additionally needsconfirmFolder: 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 ofdrive_trash_filefor an accepted list: up to 100 rows in one call, processed in order, one result row per item withtrashed,wouldTrashorrefusedand 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 whatsheet_append_rowsandsheet_update_cellsare for.valueInputisUSER_ENTEREDby default (numbers and dates parsed as when typed) orRAW(every cell literal text). Uses the Sheets API under the existingdrivescope. 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.appendwithINSERT_ROWS), on My Drive or a shared drive. Never overwrites a cell.sheetis the exact tab title; an unknown one is refused with the list of tabs. Up to 1000 rows and 20 000 cells per call;valueInputas indrive_create_spreadsheet, so with the defaultUSER_ENTEREDa cell starting with=becomes a formula. Formulas that name their own row need its number: withexpectedStartRowthe 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, anoticesays 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.rangeis bounded A1 notation without a tab name (B7,B7:D9), at most 50 cells;valuesandexpectedValuesmust have exactly its shape,""for an empty cell (and""invaluesclears one).expectedValuesmust equal what the cells show now — the formatted textdrive_export_filereturns — or the call is refused with each differing cell. Withoutconfirm: trueit changes nothing and returns a preview:before,after,mismatches, and the formulas in the range (formulasBefore). Replacing a formula additionally needsconfirmFormulas: true. A range reaching past the tab's existing data is refused and pointed atsheet_append_rows. The result carriesbefore,after(read back, formatted),updatedCellsandchangedCells. 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;sheetpicks 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'stextis capped at 200 KB, cut on a line boundary; when cut,truncated: trueand the full text is written intoOCTOMAIL_DOWNLOAD_DIR/<account>with the path insavedTo, never overwriting an existing file. Sheets are read through the Google Sheets API under the existingdrivescope, 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 atdrive_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.filePathmust resolve insideOCTOMAIL_DOWNLOAD_DIR/<account>(relative paths resolve against it), the same rulegmail_create_draftapplies 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. WithconvertToGoogleDoc: 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 unlessnameis 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) intoOCTOMAIL_DOWNLOAD_DIR/<account>, or anoutDirinside it (created if missing; a path outside is refused), undernameor the Drive name with unsafe characters replaced. Returns the path assavedToand never the content. A Google Doc, Sheet or other Google-native file, and a folder, are refused with a pointer todrive_export_file. A file overmaxBytes(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 withverified(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 |
Creating the Google Cloud project, OAuth consent screen, and the 7-day token expiry to avoid | |
Aliases, | |
Wiring the server into Claude Code, Claude Desktop, and Codex | |
Fixes for common authorization and config errors | |
Field-tested workflow and lessons for cleaning up a mailbox with filters, backfills, and verification | |
The no-real-user-data rule for code, tests and docs, and the 2026-09-14 history rewrite |
Commands
Command | What it does |
| Interactive wizard: collects OAuth credentials, authorizes accounts, verifies them, prints client config |
| Authorizes (or re-authorizes) one account by alias |
| Checks environment, build freshness, and every configured account; exits 1 on failure |
| Compiles TypeScript to |
| Runs the server directly from source with |
| Runs the test suite |
Notes
gmail_apply_labelsaccepts label display names or Gmail label IDs.gmail_search_manysearches all configured accounts whenaccountsis omitted, and returns per-account errors without hiding successful results from other accounts.gmail_archiveonly removes theINBOXlabel.gmail_create_draftandgmail_update_draftcreate or replace a draft only;gmail_send_draftis 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 toolscalendar_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_searchA
Search Gmail messages on one 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), account (required), maxResults.
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
Scored across 41 tools
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.
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.
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.
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
Related MCP Connectors
Hosted email MCP for your own Gmail, Outlook.com, Microsoft 365, iCloud or IMAP inbox: read, search, draft, reply in thread, forward and file mail. It moves or flags up to 500 messages in one call, and a send leaves exactly one copy in Sent. A calendar is a separate connection, and connecting one adds diary and scheduling tools.
A MCP server for Gmail that lets you search, read, and draft emails and replies.
Hosted MCP server for your Gmail, Outlook and IMAP mail, with mailboxes and scopes set per agent.
Gmail for agents: create inboxes, read and reply to mail, send email, manage domains. OAuth sign-in.
Related MCP Servers
- AlicenseAqualityCmaintenanceConnect 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.2217 npm9MIT
- FlicenseNot gradedqualityBmaintenanceEnables interacting with multiple Gmail accounts through a single MCP server, supporting search, labels, drafts, and thread management with per-account OAuth.1-
- FlicenseNot gradedqualityDmaintenanceMulti-account Gmail MCP server for reading threads, managing labels, and creating drafts across multiple Gmail accounts.-
- FlicenseNot gradedqualityDmaintenanceEnables searching, reading, and drafting emails across multiple Gmail accounts through a single MCP server.-