gogcli-mcp-gmail#

Extended Gmail MCP server via gogcli — 61 tools: 8 auth + 4 base Gmail + 49 extra dedicated Gmail tools.

• Source: github.com/chrischall/gogcli-mcp

Requirements#

• gogcli installed and authenticated
• Node.js 22 or later

Setup#

json

{
  "mcpServers": {
    "gogcli-gmail": {
      "command": "npx",
      "args": ["-y", "gogcli-mcp-gmail"],
      "env": {
        "GOG_ACCOUNT": "you@gmail.com"
      }
    }
  }
}

Extra Gmail Tools#

Read#

ToolWhat it doesgog_gmail_rawRaw Gmail API JSON for a messagegog_gmail_attachmentDownload an attachment by attachmentIndex (or legacy attachmentId) and deliver its contents — inline when within inlineMaxBytes (3 MiB default, 10 MiB max — larger values are clamped), else a server-side file path — use url/ drive when hosted ( deliver: auto/inline/drive/url/off). deliver="url" gives a signed link curl can fetch with no credential, for an hour — hosted deployments onlygog_gmail_urlPrint web URLs for threadsgog_gmail_historyList history events since a historyIdgog_gmail_messages_searchSearch individual messages, not threads — one row per message

Threads#

ToolWhat it doesgog_gmail_thread_getGet a thread with all messagesgog_gmail_thread_modifyModify labels on a threadgog_gmail_thread_attachmentsList all attachments in a thread (fetch each with gog_gmail_attachment)

Labels#

ToolWhat it doesgog_gmail_labels_listList all labelsgog_gmail_labels_getGet a label's details and countsgog_gmail_labels_createCreate a new labelgog_gmail_labels_renameRename a labelgog_gmail_labels_deleteDelete a labelgog_gmail_labels_modifyModify labels on one or more threadsgog_gmail_labels_styleChange a label's color or visibility

Bulk operations#

ToolWhat it doesgog_gmail_archiveArchive by IDs or querygog_gmail_mark_readMark read by IDs or querygog_gmail_mark_unreadMark unread by IDs or querygog_gmail_trashTrash by IDs or querygog_gmail_message_modifyModify labels on a single messagegog_gmail_batch_deletePermanently delete multiple messagesgog_gmail_batch_modifyModify labels on multiple messages

Drafts#

ToolWhat it doesgog_gmail_drafts_listList drafts (+ free origin/ rootsOwnThread)gog_gmail_drafts_getGet a draftgog_gmail_drafts_createCreate a draftgog_gmail_drafts_updateUpdate a draft; replyToThreadId re-threads it in place (same id) + threadingVerification; forkSiblingDraftId blocks a body overwrite that would drop the other copy's textgog_gmail_drafts_deleteDelete a draftgog_gmail_drafts_sendSend a draft after the user confirms a preview of it (404 → DRAFT_FORKED, or GOOGLE_404_NOT_THE_DRAFT if the draft is still listed)gog_gmail_drafts_diffDiff two drafts (body divergence, threading loss, fork verdict)gog_gmail_drafts_replySave a reply as a draft — inherited recipients, subject and quote; never sendsgog_gmail_drafts_reply_allSave a reply-all as a draft; never sendsgog_gmail_drafts_forwardSave a forward as a draft; recipients optional, so it can be staged without any

A draft edited in a mail client is replaced, not updated: the old id 404s. drafts_update / drafts_send answer that 404 with a DRAFT_FORKED report (what happened, the drafts that exist, what to do) instead of a bare notFound, at a bounded cost of ≤2 extra gog calls. It never names a replacement — the 404'd draft cannot be fetched, so no lineage signal can exist; use drafts_diff on a named pair for that. The 404 is attributed first: replyToThreadId and replyToMessageId resolve their own entities and 404 identically, so if the draft id is still in the listing the answer is GOOGLE_404_NOT_THE_DRAFT — no fork claimed, reply target named. That listing is capped at 20, so listingEvidence says what it can carry: only a complete-listing (the window came back short, i.e. it covered the folder) claims the draft is gone; capped-listing and listing-unavailable say in words that they establish nothing. A reply target, when one was passed, is echoed and explained first.

drafts_diff confirms a pairing only on a link from the candidate to the original (its Message-Id in the candidate's In-Reply-To/ References) or on agreement over text neither draft quoted and neither client generated — the salutation, closing formula, name and signature block are excluded alongside quoting, because a client writes them identically on every message ( Hi Jennifer, + Thanks, + Chris + Sent from my iPhone is 4 lines and 43 characters of pure apparatus). A shared reply root is corroboration only — every reply in a thread has one — and none means no evidence was found, not "unrelated". To adopt the survivor back onto the thread, call drafts_update with replyToThreadId: same draft id, gog resolves the reply headers, threadingVerification reports whether it worked. It rewrites the whole body, so diff and merge first.

gog requires a body on every update, so there is no header-only edit and every adoption overwrites the body. Pass forkSiblingDraftId (the other copy's id) and the update reads that draft first — one extra gog call, zero when the param is absent — and refuses to write ( DRAFT_CONTENT_LOSS, nothing changed) if your body drops a line the sibling holds, naming the lines; acceptContentLoss: true overrides, and contentLossCheck.written then reports whether the write it authorised actually succeeded — a failed write says so and says nothing was saved. A check that could not run refuses too ( DRAFT_CONTENT_LOSS_UNCHECKED). It compares text only and never claims one draft replaced another — that is drafts_diff's job.

Write#

ToolWhat it doesgog_gmail_importImport an RFC822/EML message into the mailbox (keeps its headers/date; does not send)gog_gmail_forwardForward a messagegog_gmail_replyReply to the original sendergog_gmail_reply_allReply to sender plus every To/Cc recipientgog_gmail_autoreplyReply once to all messages matching a query

Settings#

ToolWhat it doesgog_gmail_vacation_getGet the vacation responder settingsgog_gmail_vacation_updateEnable/disable the vacation respondergog_gmail_filters_listList all filtersgog_gmail_filters_getGet a filter by IDgog_gmail_filters_createCreate a filtergog_gmail_filters_deleteDelete a filtergog_gmail_sendas_listList send-as aliasesgog_gmail_sendas_getGet one send-as aliasgog_gmail_sendas_createCreate a send-as aliasgog_gmail_sendas_updateUpdate a send-as aliasgog_gmail_sendas_deleteDelete a send-as aliasgog_gmail_sendas_verifyResend an alias verification email

Plus 8 auth tools and 4 base Gmail tools (search, get, send, run). Use gog_gmail_run for the settings with no dedicated tool ( delegates, forwarding, watch) and email tracking ( track).