A Model Context Protocol (MCP) server implementation for the Gmail API, providing a standardized interface for email management, sending, and retrieval.
<p align="center"><img height="512" src=https://github.com/user-attachments/assets/b61db02e-bde4-4386-b5a9-2b1c6a989925></p>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
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-mcp
Enter 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.git
- Install packages and build with
pnpm(inside cloned repo):
pnpm i && pnpm build
- Add 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 |
|---|---|---|---|
AUTH_SERVER_PORT | Port for the temporary OAuth authentication server | No | 3000 |
CLIENT_ID | Google API client ID (found in GMAIL_OAUTH_PATH) | Yes if remote server connection | '' |
CLIENT_SECRET | Google API client secret (found in GMAIL_OAUTH_PATH) | Yes if remote server connection | '' |
GMAIL_CREDENTIALS_PATH | Path to the user credentials file | No | MCP_CONFIG_DIR/credentials.json |
GMAIL_OAUTH_PATH | Path to the Google API Client file | No | MCP_CONFIG_DIR/gcp-oauth.keys.json |
MCP_CONFIG_DIR | Directory for storing configuration files | No | ~/.gmail-mcp |
REFRESH_TOKEN | OAuth refresh token (found in GMAIL_CREDENTIALS_PATH) | Yes if remote server connection | '' |
PORT | Port for Streamable HTTP transport method | No | 3000 |
TELEMETRY_ENABLED | Enable telemetry | No | true |
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