playbooks

home / mcp / gmail mcp server

Gmail MCP Server

Provides Gmail integration with auto authentication, enabling email send, read, search, label management, and batch operations via MCP.

Installation
Add the following to your MCP client configuration file.

Configuration

View docs
{
  "mcpServers": {
    "gongrzhe-gmail-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@gongrzhe/server-gmail-autoauth-mcp"
      ],
      "env": {
        "GMAIL_OAUTH_PATH": "/path/to/gcp-oauth.keys.json (mounted or placed locally)",
        "GMAIL_CREDENTIALS_PATH": "/gmail-server/credentials.json"
      }
    }
  }
}

Gmail AutoAuth MCP Server provides a tightly integrated Gmail control surface for Claude Desktop via the Model Context Protocol (MCP). It lets you send, read, organize, and manage Gmail using natural language interactions, all through secure OAuth2 authentication and an MCP client.

How to use

You connect to Gmail AutoAuth MCP Server from an MCP client (such as Claude Desktop) and start issuing high-level commands that map to Gmail actions. Use the available tools to send emails (with attachments), read messages, manage labels, search your mailbox, apply batch operations, and create filters. The server handles authentication automatically and stores credentials locally for convenience. Start with a simple task like sending an email, then explore reading messages, attaching files, or organizing messages with labels.

How to install

Prerequisites: install Node.js and npm on your system so you can run MCP server tooling.

# Prerequisites
node -v
npm -v

Install via Smithery (recommended for automatic setup within Claude):

npx -y @smithery/cli install @gongrzhe/server-gmail-autoauth-mcp --client claude

Manual installation and authentication steps:

# 1) Create a Google Cloud Project and enable Gmail API
# 2) Create OAuth 2.0 Credentials (Desktop or Web)
# 3) Download the JSON keys file and rename to gcp-oauth.keys.json

Authentication flow (global authentication is recommended):

# Place credentials in the global config directory
mkdir -p ~/.gmail-mcp
mv gcp-oauth.keys.json ~/.gmail-mcp/

# Authenticate from anywhere
npx @gongrzhe/server-gmail-autoauth-mcp auth

Authentication flow (local authentication):

# Place credentials in your current directory
# The file will be copied to the global config
npx @gongrzhe/server-gmail-autoauth-mcp auth

What happens during authentication: the server looks for gcp-oauth.keys.json in the current directory or in ~/.gmail-mcp; it launches your browser for Google authentication and stores credentials at ~/.gmail-mcp/credentials.json. Both Desktop app and Web app credentials are supported. For Web app credentials, add http://localhost:3000/oauth2callback to the authorized redirect URIs.

Configuration in Claude Desktop: use the MCP config snippet shown below to register the Gmail MCP server.

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

Docker users can authenticate and run the MCP server inside a container. The authentication command accepts a mounted credentials file and exposes port 3000 for OAuth callbacks. After authentication, run the server with a similar configuration as shown above in Claude Desktop.

Cloud environments (such as n8n) can specify a custom OAuth callback URL during authentication. Use a command like this to start authentication with a cloud callback URL and then configure the MCP server in your client accordingly.

npx @gongrzhe/server-gmail-autoauth-mcp auth https://gmail.gongrzhe.com/oauth2callback

Additional configuration and notes

Security: OAuth credentials are stored locally in your environment (~/.gmail-mcp/) and are used to access Gmail on your behalf. Do not share credentials. Attachments are processed locally and not stored permanently by the server.

Troubleshooting highlights: ensure the gcp-oauth.keys.json file is in the expected location, verify redirect URIs for web credentials, free port 3000 if you encounter port conflicts during authentication, and adjust batch sizes if you face rate limits during batch operations.

Notes on available commands and usage

The Gmail MCP server exposes a comprehensive set of tools for email management, including sending, reading, filtering, labeling, and batch operations. The server integrates with Gmail API and supports international characters, HTML content, and attachments.

Available tools

send_email

Send a new email immediately with support for plain text, HTML, or multipart emails, including optional attachments.

draft_email

Create a draft email with optional attachments without sending it.

read_email

Retrieve the content of a specific email by its ID, with enhanced attachment details.

download_attachment

Download an attachment from a specific email to your local filesystem.

search_emails

Search emails using Gmail search syntax with optional max results.

modify_email

Add or remove labels from emails to move them between folders or states.

delete_email

Permanently delete an email.

list_email_labels

Retrieve all available Gmail labels.

create_label

Create a new Gmail label with visibility settings.

update_label

Update an existing Gmail label, including visibility settings.

delete_label

Delete a Gmail label.

get_or_create_label

Get a label by name or create it if it does not exist.

batch_modify_emails

Modify labels for multiple emails in efficient batches.

batch_delete_emails

Permanently delete multiple emails in efficient batches.

create_filter

Create a new Gmail filter with custom criteria and actions.

list_filters

Retrieve all Gmail filters.

get_filter

Get details of a specific Gmail filter.

delete_filter

Delete a Gmail filter.

create_filter_from_template

Create a filter using pre-defined templates for common scenarios.