Gmail MCP
A Model Context Protocol (MCP) 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
Prerequisites
To run this MCP server, you first 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:```bash
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`:```javascript
{
"mcpServers": {
"gmail": {
"command": "npx",
"args": [
"@shinzolabs/gmail-mcp"
]
}
}
}
Build from Source
- Download the repo:```bash
git clone https://github.com/shinzo-labs/gmail-mcp.git
2. Install packages and build with `pnpm` (inside cloned repo):```bash
pnpm i && pnpm build
- Add the following to your MCP client
config.json:javascript { "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 |
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.