Gmail MCP Server

A Model Context Protocol (MCP) server that provides Gmail integration for AI assistants. This server allows AI assistants to read unread emails, classify them, create draft replies, and save drafts to Gmail.

Features

• Get Unread Emails: Retrieve the latest unread emails from your inbox
• Classify Emails: Automatically categorize emails as urgent, newsletter, work, personal, or unknown using HuggingFace transformers (BART-large-MNLI) with AI fallback for low-confidence predictions
• Create Draft Replies: Generate suggested email replies using AI (requires sampling support)
• Save Drafts: Save draft replies directly to Gmail

Important: Client Compatibility

Note about Sampling Support: This server uses MCP's sampling feature for the create_suggested_draft_reply tool. Different MCP clients have different levels of support:

Full Support (Sampling Enabled):

• GitHub Copilot (VS Code extension) - All tools work including AI-powered draft replies
• Other clients listed at https://modelcontextprotocol.io/clients with sampling support

Limited Support (No Sampling):

• Claude Desktop - get_unread_emails and save_draft_reply_to_gmail work, but create_suggested_draft_reply will not function

Email classification uses HuggingFace transformers with AI fallback for low-confidence predictions (< 0.7) and works in all clients.

Prerequisites

1. Node.js (v18 or higher)
2. Google Cloud Project with Gmail API enabled
3. OAuth 2.0 credentials from Google Cloud Console

Setting up Google OAuth Credentials

1. Go to Google Cloud Console
2. Create a new project or select an existing one
3. Enable the Gmail API:
   • Navigate to "APIs & Services" > "Library"
   • Search for "Gmail API" and enable it
4. Create OAuth 2.0 credentials:
   • Go to "APIs & Services" > "Credentials"
   • Click "Create Credentials" > "OAuth client ID"
   • Choose "Desktop app" as the application type
   • Important: Add http://localhost to "Authorized redirect URIs"
   • Download the credentials JSON file
5. Save the downloaded file as secrets/google-credentials.json in this project

Installation

1. Clone this repository
2. Install dependencies:

   npm install
   

3. Build the project:

   npm run build
   

4. Create a secrets directory and add your google-credentials.json file

Configuration

For Claude Desktop and GitHub Copilot

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

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

Note: Replace /absolute/path/to/gmail-mcp-server with the actual path to your cloned repository.

GitHub Copilot can also access MCP servers configured in the Claude Desktop config file, so this single configuration works for both tools.

Demo & Examples

This server has been tested with both GitHub Copilot and Claude Desktop. See the screen-shots folder for working examples:

GitHub Copilot (Full Support with Sampling)

Shows all tools working including AI-powered draft generation.

• See examples in screen-shots/copilot-sampling/

Claude Desktop (Limited Support - No Sampling)

Shows get_unread_emails and save_draft_reply_to_gmail working. The create_suggested_draft_reply tool does not work due to lack of sampling support.

• See examples in screen-shots/claude-desktop/

Example Prompts:

• "Get my last 10 unread emails"
• "Create a professional draft reply to the email from [sender] saying I'll review it tomorrow"
• "Save this draft reply to gmail"

Gmail Authorization

When you first start the server, it will automatically handle authorization:

1. The server will detect that you're not authorized
2. Your default browser will open automatically to Google's authorization page
3. Sign in with your Google account and authorize the application
4. The browser will show "Authorization successful! You can close this window."
5. The server will automatically save the token

You won't need to authorize again unless you revoke access or delete secrets/token.json.

Available Tools

get_unread_emails

Retrieves the latest unread emails from your Gmail inbox. Emails are automatically classified into categories (urgent, newsletter, work, personal, or unknown).

Parameters:

• numberOfEmails (number, 1-100): Number of emails to retrieve

create_suggested_draft_reply

Creates an AI-generated draft reply to an email.

Parameters:

• email (object): Email object to reply to
• instructions (string, optional): Additional instructions for the reply

save_draft_reply_to_gmail

Saves a draft reply to Gmail as a threaded response.

Parameters:

• draftEmail (string): The draft email content
• email (object): The email object to reply to (contains threadId for threading)

Development

Run the server in development mode:

npm run dev