Gmail MCP Server
Provides comprehensive Gmail API integration for email management, including sending and retrieving messages, managing labels and threads, creating drafts, configuring settings (vacation responder, IMAP/POP, filters, delegates), and tracking mailbox changes through OAuth2 authentication.
Uses Google Cloud Console for OAuth 2.0 authentication setup and credential management to enable secure access to Gmail API functionality.
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., "@Gmail MCP Server show me my unread emails from the last 24 hours"
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.
A Model Context Protocol (MCP) server implementation for the Gmail API, providing a standardized interface for email management, sending, and retrieval.
Features
Complete Gmail API coverage including messages, threads, labels, drafts, and settings
Support for sending, drafting, and managing emails
Label management with customizable colors and visibility settings
Thread operations for conversation management
Settings management including vacation responder, IMAP/POP, and language settings
History tracking for mailbox changes
Secure OAuth2 authentication using Google Cloud credentials
Related MCP server: Gmail MCP
Prerequisites
Dependencies
For simplest installation, install Node.js 18+. If you would like to build locally, you will also need to install pnpm.
Google Workspace Setup
To run this MCP server, you will need to set up a Google API Client for your organization, with each user running a script to retrieve their own OAuth refresh token.
Google API Client Setup (once per organization)
Go to the Google Cloud Console.
Create a new project or select an existing one.
Enable the Gmail API for your project.
Go to Credentials and create an OAuth 2.0 Client ID. Choose "Desktop app" for the client type.
Download and save the OAuth keys JSON as
~/.gmail-mcp/gcp-oauth.keys.json. ⚠️ NOTE: to create~/.gmail-mcp/through MacOS's Finder app you need to enable hidden files first.(Optional) For remote server installation (ex. using Smithery CLI), note the
CLIENT_IDandCLIENT_SECRETfrom this file.
Client OAuth (once per user)
Have the user copy
~/.gmail-mcp/gcp-oauth.keys.jsonto their computer at the same path.Run
npx @shinzolabs/gmail-mcp auth.A browser window will open where the user may select a profile, review the requested scopes, and approve.
(Optional) For remote server installation, note the file path mentioned in the success message (
~/.gmail-mcp/credentials.jsonby default). The user'sREFRESH_TOKENwill be found here.
Client Configuration
There are several options to configure your MCP client with the server. For hosted/remote server setup, use Smithery's CLI with a Smithery API Key. For local installation, use npx or build from source. Each of these options is explained below.
Smithery Remote Server (Recommended)
To add a remote server to your MCP client config.json, run the following command from Smithery CLI:
npx -y @smithery/cli install @shinzo-labs/gmail-mcpEnter your CLIENT_ID, CLIENT_SECRET, and REFRESH_TOKEN when prompted.
Smithery SDK
If you are developing your own agent application, you can use the boilerplate code here.
NPX Local Install
To install the server locally with npx, add the following to your MCP client config.json:
{
"mcpServers": {
"gmail": {
"command": "npx",
"args": [
"@shinzolabs/gmail-mcp"
]
}
}
}Build from Source
Download the repo:
git clone https://github.com/shinzo-labs/gmail-mcp.gitInstall packages and build with
pnpm(inside cloned repo):
pnpm i && pnpm buildAdd the following to your MCP client
config.json:
{
"mcpServers": {
"gmail": {
"command": "node",
"args": [
"/path/to/gmail-mcp/dist/index.js"
]
}
}
}Config Variables
Variable | Description | Required? | Default |
| Port for the temporary OAuth authentication server | No |
|
| Google API client ID (found in | Yes if remote server connection |
|
| Google API client secret (found in | Yes if remote server connection |
|
| Path to the user credentials file | No |
|
| Path to the Google API Client file | No |
|
| Directory for storing configuration files | No |
|
| OAuth refresh token (found in | Yes if remote server connection |
|
| Port for Streamable HTTP transport method | No |
|
| Enable telemetry | No |
|
Supported Endpoints
User Management
get_profile: Get the current user's Gmail profilestop_mail_watch: Stop receiving push notificationswatch_mailbox: Set up push notifications for mailbox changes
Message Management
Managing Messages
list_messages: List messages with optional filteringget_message: Get a specific messageget_attachment: Get a message attachmentmodify_message: Modify message labelssend_message: Send an email message to specified recipientsdelete_message: Permanently delete a messagetrash_message: Move message to trashuntrash_message: Remove message from trashbatch_modify_messages: Modify multiple messagesbatch_delete_messages: Delete multiple messages
Label Management
list_labels: List all labelsget_label: Get a specific labelcreate_label: Create a new labelupdate_label: Update a labelpatch_label: Partial update of a labeldelete_label: Delete a label
Thread Management
list_threads: List email threadsget_thread: Get a specific threadmodify_thread: Modify thread labelstrash_thread: Move thread to trashuntrash_thread: Remove thread from trashdelete_thread: Delete a thread
Draft Management
list_drafts: List drafts in the user's mailboxget_draft: Get a specific draft by IDcreate_draft: Create a draft email in Gmailupdate_draft: Replace a draft's contentdelete_draft: Delete a draftsend_draft: Send an existing draft
Settings Management
Auto-Forwarding
get_auto_forwarding: Get auto-forwarding settingsupdate_auto_forwarding: Update auto-forwarding settings
IMAP Settings
get_imap: Get IMAP settingsupdate_imap: Update IMAP settings
POP Settings
get_pop: Get POP settingsupdate_pop: Update POP settings
Vacation Responder
get_vacation: Get vacation responder settingsupdate_vacation: Update vacation responder
Language Settings
get_language: Get language settingsupdate_language: Update language settings
Delegates
list_delegates: List account delegatesget_delegate: Get a specific delegateadd_delegate: Add a delegateremove_delegate: Remove a delegate
Filters
list_filters: List email filtersget_filter: Get a specific filtercreate_filter: Create a new filterdelete_filter: Delete a filter
Forwarding Addresses
list_forwarding_addresses: List forwarding addressesget_forwarding_address: Get a specific forwarding addresscreate_forwarding_address: Create a forwarding addressdelete_forwarding_address: Delete a forwarding address
Send-As Settings
list_send_as: List send-as aliasesget_send_as: Get a specific send-as aliascreate_send_as: Create a send-as aliasupdate_send_as: Update a send-as aliaspatch_send_as: Partial update of a send-as aliasverify_send_as: Send verification emaildelete_send_as: Delete a send-as alias
S/MIME Settings
list_smime_info: List S/MIME configurationsget_smime_info: Get a specific S/MIME configinsert_smime_info: Upload a new S/MIME configset_default_smime_info: Set default S/MIME configdelete_smime_info: Delete an S/MIME config
Contributing
Contributions are welcomed and encouraged! Please read CONTRIBUTING.md for guidelines on issues, contributions, and contact information.
Data Collection and Privacy
Shinzo Labs collects limited anonymous telemetry from this server to help improve our products and services. No personally identifiable information is collected as part of this process. Please review the Privacy Policy for more details on the types of data collected and how to opt-out of this telemetry.
License
MIT
Available Tools
64 toolsadd_delegateC
Adds a delegate to the specified account
Inputs: delegateEmail (required).
batch_delete_messagesB
Delete multiple messages
Inputs: ids (required).
batch_modify_messagesB
Modify the labels on multiple messages
Inputs: ids (required), addLabelIds, removeLabelIds.
create_draftB
Create a draft email in Gmail. Note the mechanics of the raw parameter.
Inputs: raw, threadId, to, cc, +4 more.
create_filterD
Creates a filter
Inputs: criteria (required), action (required).
create_forwarding_addressB
Creates a forwarding address
Inputs: forwardingEmail (required).
create_labelC
Create a new label
Inputs: name (required), messageListVisibility, labelListVisibility, color.
create_send_asB
Creates a custom send-as alias
Inputs: sendAsEmail (required), displayName, replyToAddress, signature, +2 more.
delete_draftC
Delete a draft
Inputs: id (required).
delete_filterB
Deletes a filter
Inputs: id (required).
delete_forwarding_addressB
Deletes the specified forwarding address
Inputs: forwardingEmail (required).
delete_labelC
Delete a label
Inputs: id (required).
delete_messageA
Immediately and permanently delete a message
Inputs: id (required).
delete_send_asB
Deletes the specified send-as alias
Inputs: sendAsEmail (required).
delete_smime_infoB
Deletes the specified S/MIME config for the specified send-as alias
Inputs: sendAsEmail (required), id (required).
delete_threadB
Delete a thread
Inputs: id (required).
get_attachmentC
Get a message attachment
Inputs: messageId (required), id (required).
get_auto_forwardingA
Gets auto-forwarding settings
Inputs: no named parameters.
get_delegateA
Gets the specified delegate
Inputs: delegateEmail (required).
get_draftC
Get a specific draft by ID
Inputs: id (required), includeBodyHtml.
get_filterC
Gets a filter
Inputs: id (required).
get_forwarding_addressC
Gets the specified forwarding address
Inputs: forwardingEmail (required).
get_imapB
Gets IMAP settings
Inputs: no named parameters.
get_labelA
Get a specific label by ID
Inputs: id (required).
get_languageB
Gets language settings
Inputs: no named parameters.
get_messageA
Get a specific message by ID with format options
Inputs: id (required), includeBodyHtml.
get_popB
Gets POP settings
Inputs: no named parameters.
get_profileA
Get the current user's Gmail profile
Inputs: no named parameters.
get_send_asA
Gets the specified send-as alias
Inputs: sendAsEmail (required).
get_smime_infoB
Gets the specified S/MIME config for the specified send-as alias
Inputs: sendAsEmail (required), id (required).
get_threadB
Get a specific thread by ID
Inputs: id (required), includeBodyHtml.
get_vacationB
Get vacation responder settings
Inputs: no named parameters.
insert_smime_infoB
Insert (upload) the given S/MIME config for the specified send-as alias
Inputs: sendAsEmail (required), encryptedKeyPassword (required), pkcs12 (required).
list_delegatesA
Lists the delegates for the specified account
Inputs: no named parameters.
list_draftsC
List drafts in the user's mailbox
Inputs: maxResults, q, includeSpamTrash, includeBodyHtml.
list_filtersA
Lists the message filters of a Gmail user
Inputs: no named parameters.
list_forwarding_addressesB
Lists the forwarding addresses for the specified account
Inputs: no named parameters.
list_labelsB
List all labels in the user's mailbox
Inputs: no named parameters.
list_messagesC
List messages in the user's mailbox with optional filtering
Inputs: maxResults, pageToken, q, labelIds, +2 more.
list_send_asB
Lists the send-as aliases for the specified account
Inputs: no named parameters.
list_smime_infoB
Lists S/MIME configs for the specified send-as alias
Inputs: sendAsEmail (required).
list_threadsB
List threads in the user's mailbox
Inputs: maxResults, pageToken, q, labelIds, +2 more.
modify_messageB
Modify the labels on a message
Inputs: id (required), addLabelIds, removeLabelIds.
modify_threadB
Modify the labels applied to a thread
Inputs: id (required), addLabelIds, removeLabelIds.
patch_labelB
Patch an existing label (partial update)
Inputs: id (required), name, messageListVisibility, labelListVisibility, +1 more.
patch_send_asC
Patches the specified send-as alias
Inputs: sendAsEmail (required), displayName, replyToAddress, signature, +2 more.
remove_delegateC
Removes the specified delegate
Inputs: delegateEmail (required).
send_draftC
Send an existing draft
Inputs: id (required).
send_messageC
Send an email message to specified recipients. Note the mechanics of the raw parameter.
Inputs: raw, threadId, to, cc, +4 more.
set_default_smime_infoC
Sets the default S/MIME config for the specified send-as alias
Inputs: sendAsEmail (required), id (required).
stop_mail_watchB
Stop receiving push notifications for the given user mailbox
Inputs: no named parameters.
trash_messageA
Move a message to the trash
Inputs: id (required).
trash_threadB
Move a thread to the trash
Inputs: id (required).
untrash_messageB
Remove a message from the trash
Inputs: id (required).
untrash_threadA
Remove a thread from the trash
Inputs: id (required).
update_auto_forwardingC
Updates automatic forwarding settings
Inputs: enabled (required), emailAddress (required), disposition (required).
update_imapC
Updates IMAP settings
Inputs: enabled (required), expungeBehavior, maxFolderSize.
update_labelC
Update an existing label
Inputs: id (required), name, messageListVisibility, labelListVisibility, +1 more.
update_languageC
Updates language settings
Inputs: displayLanguage (required).
update_popC
Updates POP settings
Inputs: accessWindow (required), disposition (required).
update_send_asC
Updates a send-as alias
Inputs: sendAsEmail (required), displayName, replyToAddress, signature, +2 more.
update_vacationC
Update vacation responder settings
Inputs: enableAutoReply (required), responseBodyPlainText (required), responseSubject, restrictToContacts, +3 more.
verify_send_asB
Sends a verification email to the specified send-as alias
Inputs: sendAsEmail (required).
watch_mailboxC
Watch for changes to the user's mailbox
Inputs: topicName (required), labelIds, labelFilterAction.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 64 tools
Most tools have distinct purposes targeting specific Gmail resources like messages, drafts, labels, filters, delegates, and settings. However, some overlap exists between batch_modify_messages and modify_message, and between trash/untrash operations for messages and threads, which could cause minor confusion. Overall, descriptions are clear enough to differentiate them in most cases.
Tool names follow a highly consistent verb_noun pattern throughout, such as create_draft, delete_label, get_attachment, update_vacation, and list_threads. All tools use snake_case without deviation, making them predictable and easy to parse for an agent.
With 64 tools, this server is excessively large for a typical MCP scope, likely overwhelming for agents and increasing complexity. While Gmail is a broad domain, many tools could be consolidated (e.g., separate trash/untrash for messages and threads) or omitted for a more focused interface. This count feels heavy and unwieldy.
The tool set provides comprehensive coverage of Gmail's functionality, including CRUD operations for messages, drafts, labels, filters, delegates, and send-as aliases, plus settings management for forwarding, IMAP/POP, language, vacation responders, and S/MIME. There are no obvious gaps; agents can handle full email workflows from creation to deletion.
Maintenance
Related MCP Connectors
Manage Gmail end-to-end: search, read, send, draft, label, and organize threads. Automate workflow…
Manage Gmail messages, threads, labels, drafts, and settings from your workflows. Send and organiz…
Gmail for agents: create inboxes, read and reply to mail, send email, manage domains. OAuth sign-in.
Permissioned access to Gmail, Drive and Calendar via the user's own Google account
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables interaction with Gmail through the Gmail API with OAuth2 authentication. Supports reading, sending, searching emails, and managing read status through natural language.-
- AlicenseCqualityDmaintenanceEnables comprehensive Gmail management through the Gmail API, including sending/receiving emails, organizing labels and threads, managing drafts, and configuring account settings with secure OAuth2 authentication.64732 npm1MIT
- AlicenseBqualityDmaintenanceEnables comprehensive Gmail management including sending, reading, and organizing emails, managing labels, drafts, threads, and configuring account settings through the Gmail API with secure OAuth2 authentication.64732 npmMIT
- AlicenseNot gradedqualityBmaintenanceEnables reading, sending, archiving, and managing Gmail emails and labels through Google OAuth authentication, acting as an OAuth proxy to the Gmail API.239 npm12MIT