Gmail MCP

Install

Works with Claude Code, Codex, VS Code, Cursor, Windsurf, Claude Desktop. Read the repository before you give any tool access to your data.

npx agentmarket install connector/a1-x-tech-mcp-google-gmail

About

No reviews yet. Installed it? Reviews come from verified installers only. How reviews work

Permissions

What this server can do and what it asks for, from its tool list and install config. Checked Oct 25, 2026.

Tools

8 read · 1 write · 9 delete

Secrets

3 (API keys, tokens or passwords)

Install scripts

Not scanned yet

Runs as

Node.js package

Tools (18)

Read from the source code; the running server may differ. Descriptions are the server’s own words; hidden characters are shown as [U+…].

• create_draftCreate a draft

  Creates a draft email in the mailbox without sending anything. All fields are optional — an empty draft is legal — but a useful one carries to[], subject and a body. For a reply draft set thread_id, in_reply_to (headers.messageId of the message being answered, via get_message) and the original subject with "Re: ". Returns the draft id (needed by update_draft/send_draft/delete_draft) and the underlying message id/threadId. Drafting first and sending with send_draft after a human look is the safe path for consequential mail — prefer it over send_message when in doubt.

• delete_draftDelete a draftcan change or delete data

  PERMANENTLY deletes a draft — drafts skip the trash, so there is no undo and no manage_trash recovery. Confirm with get_draft before deleting anything the user might still want. Returns empty on success.

• get_draftRead a draftread-only

  Fetches one draft with its message decoded like get_message: headers (to, cc, subject, ...), text body, HTML only on request, attachment metadata. Use it to show the user what send_draft would send, or to read the current content before update_draft (updates REPLACE the whole draft).

• get_messageRead a messageread-only

  Fetches one message fully decoded: headers (from, to, cc, subject, date, messageId, inReplyTo, references — RFC 2047 words decoded), the plain-text body (base64/charset decoded), the HTML body when there is no text part or include_html=true, and attachment METADATA (filename, mimeType, sizeBytes, attachmentId — never the content; download bytes via raw_request users/me/messages/<id>/attachments/<attachmentId> if truly needed). Bodies are truncated at max_body_chars (default 50000) with textTruncated/htmlTruncated flags. metadata_only=true skips bodies entirely. To reply later, keep headers.mes…

• get_profileGet the mailbox profileread-only

  Returns the authenticated mailbox's profile: emailAddress (the user's own address — useful for send-to-self checks and for recognizing the user's messages in threads), messagesTotal, threadsTotal and historyId. The cheapest way to verify that the OAuth credentials work.

• get_threadRead a whole conversationread-only

  Fetches a conversation with every message decoded like get_message: headers, text bodies (HTML only when a message has no text part or include_html=true), attachment metadata and truncation flags. Messages come oldest-first. To reply to the conversation, take the LAST message's threadId, headers.messageId and subject and pass them to send_message (thread_id, in_reply_to, subject with "Re: "). Long threads can be large — lower max_body_chars (it applies per message) when only the gist is needed.

• list_draftsList draftsread-only

  Lists the mailbox's drafts: draft id plus the underlying message's id and threadId (no subjects — read one with get_draft). query filters with Gmail query syntax (e.g. subject:invoice); paginate with page_token from nextPageToken.

• list_labelsList labelsread-only

  Without label_id: lists every label in the mailbox — system labels (INBOX, SENT, DRAFT, SPAM, TRASH, UNREAD, STARRED, IMPORTANT, CATEGORY_*) and user labels with their ids — the vocabulary that list_messages label_ids and modify_message add/remove_label_ids speak. With label_id: fetches that one label including its counts (messagesTotal, messagesUnread, threadsTotal, threadsUnread), which the plain list does not carry.

• list_messagesSearch and list messagesread-only

  Searches the mailbox with Gmail query syntax and returns one summary per message: id, threadId, labelIds, snippet, from, to, subject, date, internalDate. Filter with query (same operators as the Gmail search box: from:, to:, subject:, is:unread, is:starred, has:attachment, label:, newer_than:7d, before:/after:) and/or label_ids (all must match). Spam and trash are excluded unless include_spam_trash=true. Paginate with page_token from nextPageToken; page_size defaults to 25 (max 100 — each summary costs one metadata read, throttled to a few at a time). A message deleted between the search and i…

• list_threadsSearch and list threadsread-only

  Searches conversations (threads) with the same Gmail query syntax as list_messages and returns id, snippet (of the latest message) and historyId per thread. Use this instead of list_messages when the unit of work is a conversation — triaging an inbox, finding a discussion to reply into. Filter with query and/or label_ids; paginate with page_token from nextPageToken (page_size max 500). Read the full conversation with get_thread.

• manage_labelsCreate, rename or delete a labelcan change or delete data

  Manages user labels. action=create needs name (nest with "/", e.g. "Clients/Acme" — the parent must already exist). action=update needs label_id plus at least one of name, label_list_visibility (show | show_if_unread | hide — the label in the sidebar) or message_list_visibility (show | hide — its messages in the list); only the provided fields change. action=delete needs label_id and removes the label from EVERY message it was applied to — the messages survive, the label and its message-associations do not; this cannot be undone. System labels (INBOX, STARRED, ...) cannot be created, renamed o…

• manage_trashTrash or restore mailcan change or delete data

  Moves a message or a whole thread to the Gmail trash, or restores it. action=trash is REVERSIBLE: Gmail keeps trashed mail for about 30 days, then deletes it permanently; action=untrash restores it before that happens. target=message (default) uses a message id, target=thread trashes/restores every message in the thread. This server intentionally has no permanent-delete tool — the trash is the safety net. Note: untrash does not re-add INBOX; follow up with modify_message archived=false if it should reappear in the inbox.

• modify_messageChange message labels / statecan change or delete data

  Changes a message's state via Gmail labels: read=true/false marks read/unread, starred=true/false stars/unstars, archived=true removes it from the inbox (archived=false moves it back), and add_label_ids/remove_label_ids apply or strip any labels from list_labels (e.g. a user label, or IMPORTANT). At least one change is required; applying the same change twice is harmless. This never deletes anything — use manage_trash for the trash. Returns the message's new id/labelIds.

• modify_threadChange thread labels / statecan change or delete data

  Applies the same normalized state changes as modify_message — read/unread, starred, archived, add_label_ids/remove_label_ids — to EVERY message in a conversation at once. Use it to mark a whole conversation read or archive it in one call instead of looping over messages. At least one change is required; repeating the same change is harmless. Returns the thread's new id and message label state.

• raw_requestRaw Gmail API callcan change or delete data

  Escape hatch to call any Gmail API v1 path directly, for requests the typed tools don't cover — e.g. downloading attachment content ("gmail/v1/users/me/messages/<messageId>/attachments/<attachmentId>", returns base64url data), history.list for incremental sync ("gmail/v1/users/me/history?startHistoryId=..."), batchModify, or settings endpoints (filters, forwarding, vacation). The path may carry a query string. The Bearer token is added automatically; the method defaults to GET. CAUTION: this bypasses the typed tools' guard rails — users/me/messages/<id> DELETE is a PERMANENT delete that skips …

Signals

Stars

0

Forks

0

Open issues

0

Last commit

Oct 4, 2026 (24 days ago)

Last release

Sep 23, 2026 (1 month ago)

From GitHub (fetched Oct 24, 2026).

Details

Registry name

io.github.A1-x-Tech/mcp-google-gmail

Version

1.0.0

Auth

API key

Packages

npm mcp-google-gmail

License

MIT

Repository

github.com/A1-x-Tech/mcp-google-gmail

Website

github.com/A1-x-Tech/mcp-google-gmail#readme

First seen

Oct 24, 2026

Last checked

Oct 25, 2026

Source

Official MCP Registrygithub-graphql