@shinzolabs/gmail-mcp

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

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)

1. Go to the Google Cloud Console.
2. Create a new project or select an existing one.
3. Enable the Gmail API for your project.
4. Go to Credentials and create an OAuth 2.0 Client ID. Choose "Desktop app" for the client type.
5. 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.
6. (Optional) For remote server installation (ex. using Smithery CLI), note the CLIENT_ID and CLIENT_SECRET from this file.

Client OAuth (once per user)

1. Have the user copy ~/.gmail-mcp/gcp-oauth.keys.json to their computer at the same path.
2. Run npx @shinzolabs/gmail-mcp auth.
3. A browser window will open where the user may select a profile, review the requested scopes, and approve.
4. (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

1. Download the repo:

git clone https://github.com/shinzo-labs/gmail-mcp.git

2. Install packages and build with pnpm (inside cloned repo):

pnpm i && pnpm build

3. 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.