Claude MarketplacesSubmit
domdomegg avatar

Gmail

domdomegg/gmail-mcp

This connects Claude to Gmail via OAuth, exposing the full Gmail API as MCP tools. You get message and thread operations (list, get, send, forward, modify), draft management, labels, filters, attachments, and vacation responders. The server acts as an OAuth proxy so you don't store tokens yourself. It runs locally over HTTP and handles the Google OAuth dance automatically. Reach for this when you want Claude to handle email workflows like finding receipts for expense reports, tracking packages by digging through shipping notifications, or setting up vacation mode across multiple services. The thread-based tools are generally preferred over individual message operations for better context.

GitHub stars
12
tools
20
auth
Secret needed
transport
STDIO, HTTP
env vars
4
last updated
Jul 27, 2026
View on GitHub

Tools

20 tools

Public tool metadata for what this MCP can expose to an agent.

GMAIL_ADD_LABEL_TO_EMAILAdds and/or removes specified gmail labels for a message; ensure `message id` and all `label ids` are valid (use 'listlabels' for custom label ids).4 params

Adds and/or removes specified gmail labels for a message; ensure `message id` and all `label ids` are valid (use 'listlabels' for custom label ids).

Parameters* required
add_label_idsarray
Label IDs to add. For custom labels, obtain IDs via 'listLabels'. System labels (e.g., 'INBOX', 'SPAM') can also be used.
message_idstring
Immutable ID of the message to modify (e.g., from 'fetchEmails' or 'fetchMessagesByThreadId').
remove_label_idsarray
Label IDs to remove. For custom labels, obtain IDs via 'listLabels'. System labels can also be used.
user_idstring
User's email address or 'me' for the authenticated user.default: me
GMAIL_CREATE_EMAIL_DRAFTCreates a gmail email draft, supporting to/cc/bcc, subject, plain/html body (ensure `is html=true` for html), attachments, and threading.10 params

Creates a gmail email draft, supporting to/cc/bcc, subject, plain/html body (ensure `is html=true` for html), attachments, and threading.

Parameters* required
attachmentobject
File to attach to the email.
bccarray
'Bcc' (blind carbon copy) recipient email addresses.
bodystring
Email body content (plain text or HTML); `is_html` must be True if HTML.
ccarray
'Cc' (carbon copy) recipient email addresses.
extra_recipientsarray
Additional 'To' recipient email addresses.
is_htmlboolean
Set to True if `body` is HTML, otherwise the action may fail.default: false
recipient_emailstring
Primary recipient's email address.
subjectstring
Email subject line.
thread_idstring
ID of an existing Gmail thread to reply to; omit for new thread.
user_idstring
User's email address or 'me' for the authenticated user.default: me
GMAIL_CREATE_LABELCreates a new label with a unique name in the specified user's gmail account.6 params

Creates a new label with a unique name in the specified user's gmail account.

Parameters* required
background_colorstring
The background color of the label, in hex (e.g., "#FFFFFF").
label_list_visibilitystring
Controls how the label is displayed in the label list in the Gmail sidebar.default: labelShow
label_namestring
The name for the new label. Must be unique within the account, non-blank, maximum length 225 characters, cannot contain ',' or '/', not only whitespace, and must not be a reserved system label (e.g...
message_list_visibilitystring
Controls how messages with this label are displayed in the message list.default: show
text_colorstring
The text color of the label, in hex (e.g., "#000000").
user_idstring
The email address of the user in whose account the label will be created.default: me
GMAIL_DELETE_DRAFTPermanently deletes a specific gmail draft using its id; ensure the draft exists and the user has necessary permissions for the given `user id`.2 params

Permanently deletes a specific gmail draft using its id; ensure the draft exists and the user has necessary permissions for the given `user id`.

Parameters* required
draft_idstring
Immutable ID of the draft to delete, typically obtained when the draft was created.
user_idstring
User's email address or 'me' for the authenticated user; 'me' is recommended.default: me
GMAIL_DELETE_MESSAGEPermanently deletes a specific email message by its id from a gmail mailbox; for `user id`, use 'me' for the authenticated user or an email address to which the authenticated user has delegated access.2 params

Permanently deletes a specific email message by its id from a gmail mailbox; for `user id`, use 'me' for the authenticated user or an email address to which the authenticated user has delegated access.

Parameters* required
message_idstring
Identifier of the email message to delete.
user_idstring
User's email address. The special value 'me' refers to the authenticated user.default: me
GMAIL_FETCH_EMAILSFetches a list of email messages from a gmail account, supporting filtering, pagination, and optional full content retrieval.9 params

Fetches a list of email messages from a gmail account, supporting filtering, pagination, and optional full content retrieval.

Parameters* required
ids_onlyboolean
If true, only returns message IDs from the list API without fetching individual message details. Fastest option for getting just message IDs and thread IDs.default: false
include_payloadboolean
Set to true to include full message payload (headers, body, attachments); false for metadata only.default: true
include_spam_trashboolean
Set to true to include messages from 'SPAM' and 'TRASH'.default: false
label_idsarray
Filter by label IDs; only messages with all specified labels are returned. Common IDs: 'INBOX', 'SPAM', 'TRASH', 'UNREAD', 'STARRED', 'IMPORTANT', 'CATEGORY_PRIMARY' (alias 'CATEGORY_PERSONAL'), 'C...
max_resultsinteger
Maximum number of messages to retrieve per page.default: 1
page_tokenstring
Token for retrieving a specific page, obtained from a previous response's `nextPageToken`. Omit for the first page.
querystring
Gmail advanced search query (e.g., 'from:user subject:meeting'). Supports operators like 'from:', 'to:', 'subject:', 'label:', 'has:attachment', 'is:unread', 'after:YYYY/MM/DD', 'before:YYYY/MM/DD'...
user_idstring
User's email address or 'me' for the authenticated user.default: me
verboseboolean
If false, uses optimized concurrent metadata fetching for faster performance (~75% improvement). If true, uses standard detailed message fetching. When false, only essential fields (subject, sender...default: true
GMAIL_FETCH_MESSAGE_BY_MESSAGE_IDFetches a specific email message by its id, provided the `message id` exists and is accessible to the authenticated `user id`.3 params

Fetches a specific email message by its id, provided the `message id` exists and is accessible to the authenticated `user id`.

Parameters* required
formatstring
Format for message content: 'minimal' (ID/labels), 'full' (complete data), 'raw' (base64url string), 'metadata' (ID/labels/headers).default: full
message_idstring
Unique ID of the email message to retrieve, obtainable from actions like 'List Messages'.
user_idstring
User's email address or 'me' for the authenticated user.default: me
GMAIL_FETCH_MESSAGE_BY_THREAD_IDRetrieves messages from a gmail thread using its `thread id`, where the thread must be accessible by the specified `user id`.3 params

Retrieves messages from a gmail thread using its `thread id`, where the thread must be accessible by the specified `user id`.

Parameters* required
page_tokenstring
Opaque page token for fetching a specific page of messages if results are paginated.default:
thread_idstring
Unique ID of the thread, obtainable from actions like 'listThreads' or 'fetchEmails'.
user_idstring
The email address of the user.default: me
GMAIL_GET_ATTACHMENTRetrieves a specific attachment by id from a message in a user's gmail mailbox, requiring valid message and attachment ids.4 params

Retrieves a specific attachment by id from a message in a user's gmail mailbox, requiring valid message and attachment ids.

Parameters* required
attachment_idstring
ID of the attachment to retrieve.
file_namestring
Desired filename for the downloaded attachment.
message_idstring
Immutable ID of the message containing the attachment.
user_idstring
User's email address ('me' for authenticated user).default: me
GMAIL_GET_CONTACTSFetches contacts (connections) for the authenticated google account, allowing selection of specific data fields and pagination.4 params

Fetches contacts (connections) for the authenticated google account, allowing selection of specific data fields and pagination.

Parameters* required
include_other_contactsboolean
Include 'Other Contacts' (interacted with but not explicitly saved) in addition to regular contacts; if true, fetches from both endpoints and merges results.default: true
page_tokenstring
Token to retrieve a specific page of results, obtained from 'nextPageToken' in a previous response.
person_fieldsstring
Comma-separated person fields to retrieve for each contact (e.g., 'names,emailAddresses').default: emailAddresses,names,birthdays,genders
resource_namestring
Identifier for the person resource whose connections are listed; use 'people/me' for the authenticated user.default: people/me
GMAIL_GET_PEOPLERetrieves either a specific person's details (using `resource name`) or lists 'other contacts' (if `other contacts` is true), with `person fields` specifying the data to return.6 params

Retrieves either a specific person's details (using `resource name`) or lists 'other contacts' (if `other contacts` is true), with `person fields` specifying the data to return.

Parameters* required
other_contactsboolean
If true, retrieves 'Other Contacts' (people interacted with but not explicitly saved), ignoring `resource_name` and enabling pagination/sync. If false, retrieves information for the single person s...default: false
page_sizeinteger
The number of 'Other Contacts' to return per page. Applicable only when `other_contacts` is true.default: 10
page_tokenstring
An opaque token from a previous response to retrieve the next page of 'Other Contacts' results. Applicable only when `other_contacts` is true and paginating.default:
person_fieldsstring
A comma-separated field mask to restrict which fields on the person (or persons) are returned. Consult the Google People API documentation for a comprehensive list of valid fields.default: emailAddresses,names,birthdays,genders
resource_namestring
Resource name identifying the person for whom to retrieve information (like the authenticated user or a specific contact). Used only when `other_contacts` is false.default: people/me
sync_tokenstring
A token from a previous 'Other Contacts' list call to retrieve only changes since the last sync; leave empty for an initial full sync. Applicable only when `other_contacts` is true.default:
GMAIL_GET_PROFILERetrieves key gmail profile information (email address, message/thread totals, history id) for a user.1 params

Retrieves key gmail profile information (email address, message/thread totals, history id) for a user.

Parameters* required
user_idstring
The email address of the Gmail user whose profile is to be retrieved, or the special value 'me' to indicate the currently authenticated user.default: me
GMAIL_LIST_DRAFTSRetrieves a paginated list of email drafts from a user's gmail account. use verbose=true to get full draft details including subject, body, sender, and timestamp.4 params

Retrieves a paginated list of email drafts from a user's gmail account. use verbose=true to get full draft details including subject, body, sender, and timestamp.

Parameters* required
max_resultsinteger
Maximum number of drafts to return per page.default: 1
page_tokenstring
Token from a previous response to retrieve a specific page of drafts.default:
user_idstring
User's mailbox ID; use 'me' for the authenticated user.default: me
verboseboolean
If true, fetches full draft details including subject, sender, recipient, body, and timestamp. If false, returns only draft IDs (faster).default: false
GMAIL_LIST_LABELSRetrieves a list of all system and user-created labels for the specified gmail account.1 params

Retrieves a list of all system and user-created labels for the specified gmail account.

Parameters* required
user_idstring
Identifies the Gmail account (owner's email or 'me' for authenticated user) for which labels will be listed.default: me
GMAIL_LIST_THREADSRetrieves a list of email threads from a gmail account, identified by `user id` (email address or 'me'), supporting filtering and pagination.5 params

Retrieves a list of email threads from a gmail account, identified by `user id` (email address or 'me'), supporting filtering and pagination.

Parameters* required
max_resultsinteger
Maximum number of threads to return.default: 10
page_tokenstring
Token from a previous response to retrieve a specific page of results; omit for the first page.default:
querystring
Filter for threads, using Gmail search query syntax (e.g., 'from:user@example.com is:unread').default:
user_idstring
The user's email address or 'me' to specify the authenticated Gmail account.default: me
verboseboolean
If false, returns threads with basic fields (id, snippet, historyId). If true, returns threads with complete message details including headers, body, attachments, and metadata for each message in t...default: false
GMAIL_MODIFY_THREAD_LABELSAdds or removes specified existing label ids from a gmail thread, affecting all its messages; ensure the thread id is valid.4 params

Adds or removes specified existing label ids from a gmail thread, affecting all its messages; ensure the thread id is valid.

Parameters* required
add_label_idsarray
List of label IDs to add to the thread; these labels must exist.
remove_label_idsarray
List of label IDs to remove from the thread; these labels must exist.
thread_idstring
Immutable ID of the thread to modify.
user_idstring
User's email address or 'me' for the authenticated user.default: me
GMAIL_MOVE_TO_TRASHMoves an existing, non-deleted email message to the trash for the specified user.2 params

Moves an existing, non-deleted email message to the trash for the specified user.

Parameters* required
message_idstring
Identifier of the email message to move to trash.
user_idstring
User's email address or 'me' for the authenticated user.default: me
GMAIL_PATCH_LABELPatches the specified label.6 params

Patches the specified label.

Parameters* required
colorobject
The color to assign to the label. Color is only available for labels that have their `type` set to `user`.
idstring
The ID of the label to update.
labelListVisibilitystring
The visibility of the label in the label list in the Gmail web interface.
messageListVisibilitystring
The visibility of messages with this label in the message list in the Gmail web interface.
namestring
The display name of the label.
userIdstring
The user's email address. The special value `me` can be used to indicate the authenticated user.
GMAIL_REMOVE_LABELPermanently deletes a specific, existing user-created gmail label by its id for a user; cannot delete system labels.2 params

Permanently deletes a specific, existing user-created gmail label by its id for a user; cannot delete system labels.

Parameters* required
label_idstring
ID of the user-created label to be permanently deleted; must exist and not be a system label.
user_idstring
User's email address or 'me' for the authenticated user.default: me
GMAIL_REPLY_TO_THREADSends a reply within a specific gmail thread using the original thread's subject, requiring a valid `thread id` and correctly formatted email addresses. supports attachments via the `attachment` parameter with valid `s3key`, `mimetype`, and `name`.9 params

Sends a reply within a specific gmail thread using the original thread's subject, requiring a valid `thread id` and correctly formatted email addresses. supports attachments via the `attachment` parameter with valid `s3key`, `mimetype`, and `name`.

Parameters* required
attachmentobject
File to attach to the reply. Just Provide file path here
bccarray
BCC recipients' email addresses (hidden from other recipients).
ccarray
CC recipients' email addresses.
extra_recipientsarray
Additional 'To' recipients' email addresses.
is_htmlboolean
Indicates if `message_body` is HTML; if True, body must be valid HTML, if False, body should not contain HTML tags.default: false
message_bodystring
Content of the reply message, either plain text or HTML.
recipient_emailstring
Primary recipient's email address.
thread_idstring
Identifier of the Gmail thread for the reply.
user_idstring
Identifier for the user sending the reply; 'me' refers to the authenticated user.default: me

Sponsors

Promote your product hereReach 125k+ visitors monthlyPromote your product hereReach 125k+ visitors monthlyAgent CaffeineSponsoredClose your lid, come back to finished workSnugSponsoredThe clipboard manager for the AI eraPromote your product hereReach 125k+ visitors monthlyWaxSponsoredBlock anything with supervision, without erasing your iPhonePromote your product hereReach 125k+ visitors monthlyknobsSponsoredSee your site on any phone, any day, in any language

Configuration

GOOGLE_ACCESS_TOKEN*secret

Google OAuth access token with Gmail scopes.

MCP_TRANSPORT*default: http

Transport type.

GOOGLE_CLIENT_ID*

Google OAuth client ID.

GOOGLE_CLIENT_SECRET*secret

Google OAuth client secret.

Readme

gmail-mcp

MCP server for Gmail - read, send, archive, and manage emails.

Use Cases

Flight check-in: "Check me in for my flight tomorrow" → finds your confirmation email, extracts the booking reference, and completes check-in with browser use.

Expense submission: "Submit my Amazon purchases from last week as expenses" → finds receipts, extracts amounts/categories, and files them in your expense system.

Package tracking: "Where's my package from Acme?" → finds the shipping notification, extracts the tracking number, and fetches current delivery status.

Find that attachment: "What did we settle on for the budget? Michelle sent me something yesterday" → locates the email and opens the attached spreadsheet.

Vacation mode: "I'm on holiday Dec 20-Jan 2" → sets up Gmail auto-reply, blocks your calendar, and updates your Slack status in one go.

Meeting follow-up: After a call, your assistant reads the Gemini transcript, summarizes key decisions, and drafts a follow-up email with action items.

(These are just examples - any workflow that needs email search, reading, or sending can use this.)

Setup

1. Create Google OAuth credentials

View the full README on GitHub

Details

Repository
github.com/domdomegg/gmail-mcp
Website
github.com/domdomegg/gmail-mcp#readme
Category
Communication & Messaging
Package
gmail-mcp
Transport
STDIO, HTTP
Auth
Required
Registry
MCP registry, active

More from domdomegg

Related Communication & Messaging MCP servers

View all
1gx-55 avatarMulti Gmail Mcpgx-55/multi-gmail-mcpManage multiple Gmail accounts in Claude Desktop — search, send, reply, draft, and organize.11stars
2maxim-mazurok avatarMicrosoft Teams APImaxim-mazurok/teams-apiAI-native Microsoft Teams integration — read chats, send messages, search people9stars
3mintmcp avatarGmailmintmcp/serversA MCP server for Gmail that lets you search, read, and draft emails and replies.0stars
4parthjadhav avatarTelegram Notify Mcpparthjadhav/telegram-notify-mcpSend Telegram notifications from AI agents — text, photos, and documents.7stars
5samihalawa avatarSamihalawa Whatsapp Go Mcpsamihalawa/whatsapp-go-mcpScan QR codes and go! No more troublesome autos or APIs! Send text messages, images, links, locati…5stars
6adelaidasofia avatarMulti-workspace Slack MCP server with draft+confirm safety, vault auto-export, aadelaidasofia/slack-mcpMulti-workspace Slack MCP server with draft+confirm safety, vault auto-export, and triple-mode…1stars