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_emailsandsave_draft_reply_to_gmailwork, butcreate_suggested_draft_replywill not function
Email classification uses HuggingFace transformers with AI fallback for low-confidence predictions (< 0.7) and works in all clients.
Prerequisites
- Node.js (v18 or higher)
- Google Cloud Project with Gmail API enabled
- OAuth 2.0 credentials from Google Cloud Console
Setting up Google OAuth Credentials
- Go to Google Cloud Console
- Create a new project or select an existing one
- Enable the Gmail API:
- Navigate to "APIs & Services" > "Library"
- Search for "Gmail API" and enable it
- 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://localhostto "Authorized redirect URIs" - Download the credentials JSON file
- Save the downloaded file as
secrets/google-credentials.jsonin this project
Installation
- Clone this repository
- Install dependencies:
npm install - Build the project:
npm run build - Create a
secretsdirectory and add yourgoogle-credentials.jsonfile
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:
- The server will detect that you're not authorized
- Your default browser will open automatically to Google's authorization page
- Sign in with your Google account and authorize the application
- The browser will show "Authorization successful! You can close this window."
- 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 toinstructions(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 contentemail(object): The email object to reply to (contains threadId for threading)
Development
Run the server in development mode:
npm run dev