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 your Google Cloud credentials

Installation

⚠️ <strong>NOTE:</strong> Due to the large number of endpoints available on this server, it is recommended that you install and setup Heimdall to limit the number of endpoints exposed to your client applications.

To use this MCP, you'll need to set up authentication with Gmail:

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" as the application type (Warning: if you don't choose this type the server will not be able to parse the keys from your JSON file)
   • Download the client credentials JSON file
5. Save the downloaded credentials file to ~/.gmail-mcp/gcp-oauth.keys.json

NPX (Recommended)

Add the following to your MCP client config.json (~/.heimdall/config.json if using Heimdall):

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": [
        "@shinzolabs/gmail-mcp"
      ]
    }
  }
}

Manual Download

1. Download the repo:

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

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

pnpm i && pnpm run build

3. Add the following to your MCP client config.json (~/.heimdall/config.json if using Heimdall):

{
  "mcpServers": {
    "gmail": {
      "command": "node",
      "args": [
        "/path/to/gmail-mcp/dist/index.js"
      ]
    }
  }
}

Smithery

To install for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @shinzo-labs/gmail-mcp --client claude

Authentication

Automated (recommended)

This MCP provides an automated authentication flow:

1. First, acquire OAuth credentials and download the JSON file.

2. Rename the JSON file to gcp-oauth.keys.json and copy it to $HOME/.gmail-mcp/, or wherever you've set it in MCP_CONFIG_DIR.

3. Run the authentication command:

# If using npx
npx @shinzolabs/gmail-mcp auth

# If in the project directory
pnpm i && pnpm run build && pnpm run auth

4. A browser window will automatically open to the Google OAuth consent screen
5. After granting access, you can close the browser window
6. The tokens will be automatically saved to $HOME/.gmail-mcp/credentials.json

The MCP will automatically:

• Manage token refresh
• Save credentials to disk
• Handle the OAuth callback
• Open the authentication URL in your default browser

Note: by default this server uses port 3000 to listen for the OAuth response. You can set AUTH_SERVER_PORT to something else if you are running another service on 3000.

You can customize the config location by setting MCP_CONFIG_DIR before running the command (optional):

export MCP_CONFIG_DIR=/custom/path/to/directory/

Manual (suggested for Docker usage)

If you wish, you may also provide credentials directly through the environment variables:

export CLIENT_ID=your-id
export CLIENT_SECRET=your-secret
export REFRESH_TOKEN=your-refresh-token

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. Contact austin@shinzolabs.com with any questions, comments or concerns.