Summary
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.
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →
Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →
Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →
On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →
Tools
Public tool metadata for what this MCP can expose to an agent.
20 tools
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
user_idstringUser's email address or 'me' for the authenticated user.default: me
message_idstringImmutable ID of the message to modify (e.g., from 'fetchEmails' or 'fetchMessagesByThreadId').
add_label_idsarrayLabel IDs to add. For custom labels, obtain IDs via 'listLabels'. System labels (e.g., 'INBOX', 'SPAM') can also be used.
remove_label_idsarrayLabel IDs to remove. For custom labels, obtain IDs via 'listLabels'. System labels can also be used.
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
ccarray'Cc' (carbon copy) recipient email addresses.
bccarray'Bcc' (blind carbon copy) recipient email addresses.
bodystringEmail body content (plain text or HTML); `is_html` must be True if HTML.
is_htmlbooleanSet to True if `body` is HTML, otherwise the action may fail.default: false
subjectstringEmail subject line.
user_idstringUser's email address or 'me' for the authenticated user.default: me
thread_idstringID of an existing Gmail thread to reply to; omit for new thread.
attachmentobjectFile to attach to the email.
recipient_emailstringPrimary recipient's email address.
extra_recipientsarrayAdditional 'To' recipient email addresses.
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
user_idstringThe email address of the user in whose account the label will be created.default: me
label_namestringThe 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., INBOX, DRAFTS, SENT).
text_colorstringThe text color of the label, in hex (e.g., "#000000").
background_colorstringThe background color of the label, in hex (e.g., "#FFFFFF").
label_list_visibilitystringControls how the label is displayed in the label list in the Gmail sidebar.default: labelShow
message_list_visibilitystringControls how messages with this label are displayed in the message list.default: show
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
user_idstringUser's email address or 'me' for the authenticated user; 'me' is recommended.default: me
draft_idstringImmutable ID of the draft to delete, typically obtained when the draft was created.
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
user_idstringUser's email address. The special value 'me' refers to the authenticated user.default: me
message_idstringIdentifier of the email message to delete.
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
querystringGmail 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', AND/OR/NOT. Use quotes for exact phrases. Omit for no query filter.
user_idstringUser's email address or 'me' for the authenticated user.default: me
verbosebooleanIf 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, recipient, time, labels) are guaranteed.default: true
ids_onlybooleanIf 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
label_idsarrayFilter by label IDs; only messages with all specified labels are returned. Common IDs: 'INBOX', 'SPAM', 'TRASH', 'UNREAD', 'STARRED', 'IMPORTANT', 'CATEGORY_PRIMARY' (alias 'CATEGORY_PERSONAL'), 'CATEGORY_SOCIAL', 'CATEGORY_PROMOTIONS', 'CATEGORY_UPDATES', 'CATEGORY_FORUMS'. Use 'listLabels' action for custom IDs.
page_tokenstringToken for retrieving a specific page, obtained from a previous response's `nextPageToken`. Omit for the first page.
max_resultsintegerMaximum number of messages to retrieve per page.default: 1
include_payloadbooleanSet to true to include full message payload (headers, body, attachments); false for metadata only.default: true
include_spam_trashbooleanSet to true to include messages from 'SPAM' and 'TRASH'.default: false
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
formatstringFormat for message content: 'minimal' (ID/labels), 'full' (complete data), 'raw' (base64url string), 'metadata' (ID/labels/headers).default: full
user_idstringUser's email address or 'me' for the authenticated user.default: me
message_idstringUnique ID of the email message to retrieve, obtainable from actions like 'List Messages'.
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
user_idstringThe email address of the user.default: me
thread_idstringUnique ID of the thread, obtainable from actions like 'listThreads' or 'fetchEmails'.
page_tokenstringOpaque page token for fetching a specific page of messages if results are paginated.default:
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
user_idstringUser's email address ('me' for authenticated user).default: me
file_namestringDesired filename for the downloaded attachment.
message_idstringImmutable ID of the message containing the attachment.
attachment_idstringID of the attachment to retrieve.
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
page_tokenstringToken to retrieve a specific page of results, obtained from 'nextPageToken' in a previous response.
person_fieldsstringComma-separated person fields to retrieve for each contact (e.g., 'names,emailAddresses').default: emailAddresses,names,birthdays,genders
resource_namestringIdentifier for the person resource whose connections are listed; use 'people/me' for the authenticated user.default: people/me
include_other_contactsbooleanInclude 'Other Contacts' (interacted with but not explicitly saved) in addition to regular contacts; if true, fetches from both endpoints and merges results.default: true
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
page_sizeintegerThe number of 'Other Contacts' to return per page. Applicable only when `other_contacts` is true.default: 10
page_tokenstringAn 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:
sync_tokenstringA 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:
person_fieldsstringA 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_namestringResource 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
other_contactsbooleanIf 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 specified by `resource_name`.default: false
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_idstringThe 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
user_idstringUser's mailbox ID; use 'me' for the authenticated user.default: me
verbosebooleanIf true, fetches full draft details including subject, sender, recipient, body, and timestamp. If false, returns only draft IDs (faster).default: false
page_tokenstringToken from a previous response to retrieve a specific page of drafts.default:
max_resultsintegerMaximum number of drafts to return per page.default: 1
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_idstringIdentifies 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
querystringFilter for threads, using Gmail search query syntax (e.g., 'from:user@example.com is:unread').default:
user_idstringThe user's email address or 'me' to specify the authenticated Gmail account.default: me
verbosebooleanIf 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 the thread.default: false
page_tokenstringToken from a previous response to retrieve a specific page of results; omit for the first page.default:
max_resultsintegerMaximum number of threads to return.default: 10
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
user_idstringUser's email address or 'me' for the authenticated user.default: me
thread_idstringImmutable ID of the thread to modify.
add_label_idsarrayList of label IDs to add to the thread; these labels must exist.
remove_label_idsarrayList of label IDs to remove from the thread; these labels must exist.
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
user_idstringUser's email address or 'me' for the authenticated user.default: me
message_idstringIdentifier of the email message to move to trash.
GMAIL_PATCH_LABELPatches the specified label.6 params
Patches the specified label.
Parameters* required
idstringThe ID of the label to update.
namestringThe display name of the label.
colorobjectThe color to assign to the label. Color is only available for labels that have their `type` set to `user`.
userIdstringThe user's email address. The special value `me` can be used to indicate the authenticated user.
labelListVisibilitystringThe visibility of the label in the label list in the Gmail web interface.
messageListVisibilitystringThe visibility of messages with this label in the message list in the Gmail web interface.
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
user_idstringUser's email address or 'me' for the authenticated user.default: me
label_idstringID of the user-created label to be permanently deleted; must exist and not be a system label.
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
ccarrayCC recipients' email addresses.
bccarrayBCC recipients' email addresses (hidden from other recipients).
is_htmlbooleanIndicates if `message_body` is HTML; if True, body must be valid HTML, if False, body should not contain HTML tags.default: false
user_idstringIdentifier for the user sending the reply; 'me' refers to the authenticated user.default: me
thread_idstringIdentifier of the Gmail thread for the reply.
attachmentobjectFile to attach to the reply. Just Provide file path here
message_bodystringContent of the reply message, either plain text or HTML.
recipient_emailstringPrimary recipient's email address.
extra_recipientsarrayAdditional 'To' recipients' email addresses.
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
- Go to Google Cloud Console
- Create a new project (or use existing)
- Enable the Gmail API
- Go to APIs & Services → OAuth consent screen, set up consent screen
- Go to APIs & Services → Credentials → Create Credentials → OAuth client ID
- Choose Web application
- Add
http://localhost:3000/callbackto Authorized redirect URIs - Note your Client ID and Client Secret
2. Run the server
GOOGLE_CLIENT_ID='your-client-id' \
GOOGLE_CLIENT_SECRET='your-client-secret' \
MCP_TRANSPORT=http \
npm start
The server runs on http://localhost:3000 by default. Change with PORT=3001.
3. Add to your MCP client
claude mcp add --transport http gmail-mcp http://localhost:3000/mcp
Architecture
This server acts as an OAuth proxy to Google:
graph LR
A[MCP client] <--> B[gmail-mcp] <--> C[Google OAuth/API]
- Server advertises itself as an OAuth authorization server via
/.well-known/oauth-authorization-server /registerreturns the Google OAuth client credentials/authorizeredirects to Google, encoding the client's callback URL in state/callbackreceives the code from Google and forwards to the client's callback/tokenproxies token requests to Google, injecting client credentials/mcphandles MCP requests, using the bearer token to call Gmail API
The server holds no tokens or state - it just proxies OAuth to Google.
Tools
| Tool | Description |
|---|---|
gmail_get_profile | Get user's email address and profile info |
| Messages | |
gmail_messages_list | Search/list messages (consider gmail_threads_list instead) |
gmail_message_get | Get a single message |
gmail_message_send | Send an email |
gmail_message_forward | Forward an email to new recipients |
gmail_message_modify | Add/remove labels |
gmail_message_archive | Archive (remove from inbox) |
gmail_message_trash | Move to trash |
gmail_message_untrash | Restore from trash |
gmail_message_delete | Permanently delete |
gmail_messages_batch_modify | Bulk label changes |
gmail_messages_batch_delete | Bulk permanent delete |
| Threads | |
gmail_threads_list | Search/list threads (recommended) |
gmail_thread_get | Get all messages in a thread (recommended) |
gmail_thread_modify | Add/remove labels |
gmail_thread_trash | Move to trash |
gmail_thread_untrash | Restore from trash |
gmail_thread_delete | Permanently delete |
| Drafts | |
gmail_drafts_list | List drafts |
gmail_draft_get | Get a draft |
gmail_draft_create | Create a draft |
gmail_draft_update | Update a draft |
gmail_draft_send | Send a draft |
gmail_draft_delete | Delete a draft |
| Labels | |
gmail_labels_list | List all labels |
gmail_label_get | Get a label |
gmail_label_create | Create a label |
gmail_label_update | Update a label |
gmail_label_delete | Delete a label |
| Attachments | |
gmail_attachment_get | Download attachment |
| Filters | |
gmail_filters_list | List email filters |
gmail_filter_get | Get a filter |
gmail_filter_create | Create a filter |
gmail_filter_delete | Delete a filter |
| Settings | |
gmail_vacation_get | Get vacation auto-reply settings |
gmail_vacation_set | Set vacation auto-reply settings |
Gmail API Scopes
gmail.readonly- Read messages and labelsgmail.send- Send messagesgmail.modify- Modify messages (archive, labels, trash)
Contributing
Pull requests are welcomed on GitHub! To get started:
- Install Git and Node.js
- Clone the repository
- Install dependencies with
npm install - Run
npm run testto run tests - Build with
npm run build
Releases
Versions follow the semantic versioning spec.
To release:
- Use
npm version <major | minor | patch>to bump the version - Run
git push --follow-tagsto push with tags - Wait for GitHub Actions to publish to the NPM registry.
Featured
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →Configuration
GOOGLE_ACCESS_TOKEN*secretGoogle OAuth access token with Gmail scopes.
MCP_TRANSPORT*Transport type.
GOOGLE_CLIENT_ID*Google OAuth client ID.
GOOGLE_CLIENT_SECRET*secretGoogle OAuth client secret.
Categories
Registryactive
Packagegmail-mcp
TransportSTDIO, HTTP
AuthRequired
UpdatedMay 25, 2026
