article

README

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_ID and CLIENT_SECRET from this file.

Client OAuth (once per user)

Have the user copy ~/.gmail-mcp/gcp-oauth.keys.json to 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.json by default). The user's REFRESH_TOKEN will 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 |

Supported Endpoints

User Management

get_profile: Get the current user's Gmail profile
stop_mail_watch: Stop receiving push notifications
watch_mailbox: Set up push notifications for mailbox changes

Message Management

Managing Messages

list_messages: List messages with optional filtering
get_message: Get a specific message
get_attachment: Get a message attachment
modify_message: Modify message labels
send_message: Send an email message to specified recipients
delete_message: Permanently delete a message
trash_message: Move message to trash
untrash_message: Remove message from trash
batch_modify_messages: Modify multiple messages
batch_delete_messages: Delete multiple messages

Label Management

list_labels: List all labels
get_label: Get a specific label
create_label: Create a new label
update_label: Update a label
patch_label: Partial update of a label
delete_label: Delete a label

Thread Management

list_threads: List email threads
get_thread: Get a specific thread
modify_thread: Modify thread labels
trash_thread: Move thread to trash
untrash_thread: Remove thread from trash
delete_thread: Delete a thread

Draft Management

list_drafts: List drafts in the user's mailbox
get_draft: Get a specific draft by ID
create_draft: Create a draft email in Gmail
update_draft: Replace a draft's content
delete_draft: Delete a draft
send_draft: Send an existing draft

Settings Management

Auto-Forwarding

get_auto_forwarding: Get auto-forwarding settings
update_auto_forwarding: Update auto-forwarding settings

IMAP Settings

get_imap: Get IMAP settings
update_imap: Update IMAP settings

POP Settings

get_pop: Get POP settings
update_pop: Update POP settings

Vacation Responder

get_vacation: Get vacation responder settings
update_vacation: Update vacation responder

Language Settings

get_language: Get language settings
update_language: Update language settings

Delegates

list_delegates: List account delegates
get_delegate: Get a specific delegate
add_delegate: Add a delegate
remove_delegate: Remove a delegate

Filters

list_filters: List email filters
get_filter: Get a specific filter
create_filter: Create a new filter
delete_filter: Delete a filter

Forwarding Addresses

list_forwarding_addresses: List forwarding addresses
get_forwarding_address: Get a specific forwarding address
create_forwarding_address: Create a forwarding address
delete_forwarding_address: Delete a forwarding address

Send-As Settings

list_send_as: List send-as aliases
get_send_as: Get a specific send-as alias
create_send_as: Create a send-as alias
update_send_as: Update a send-as alias
patch_send_as: Partial update of a send-as alias
verify_send_as: Send verification email
delete_send_as: Delete a send-as alias

S/MIME Settings

list_smime_info: List S/MIME configurations
get_smime_info: Get a specific S/MIME config
insert_smime_info: Upload a new S/MIME config
set_default_smime_info: Set default S/MIME config
delete_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.

Gmail邮件管理控制台