Gmail MCP Server 📧

A Model Context Protocol (MCP) server that connects to Gmail API to fetch, analyze, and categorize emails automatically. This server helps you quickly identify important emails, ignore routine messages, and spot deletable promotional content.

Python Gmail API MCP OAuth2 AI Analysis
View Code Live Demo

Features

Gmail Integration

Secure OAuth2 authentication with Gmail API for safe access to your emails.

Smart Email Analysis

Automatically categorizes emails using intelligent keyword analysis and patterns.

Flexible Fetching

Get unread emails or recent messages with customizable parameters.

MCP Compatible

Works seamlessly with Claude Desktop and other MCP clients.

Email Categories

The system automatically categorizes emails into three main types:

🔴 Important: Urgent emails requiring attention 🟡 Ignorable: Regular emails that can wait 🟢 Deletable: Promotional/spam emails safe to delete

📧 Categorization Logic

Important Emails contain keywords like:

urgent, asap, important, critical, deadline, meeting, schedule, follow up, action required, boss, manager, client, customer

Deletable Emails contain keywords like:

unsubscribe, newsletter, promotion, deal, sale, discount, marketing, advertisement

Ignorable Emails

Everything else that doesn't fall into the above categories.

Setup

Prerequisites

  • Python 3.12+
  • Google Cloud Console project with Gmail API enabled
  • Gmail account

Google Cloud Setup

  1. Go to Google Cloud Console
  2. Create a new project or select existing one
  3. Enable the Gmail API
  4. Create OAuth 2.0 credentials (Desktop Application)
  5. Download the credentials as credentials.json

Installation

# Clone or download the server files # Ensure credentials.json is in the project directory # Install dependencies pip install google>=3.0.0 google-api-python-client>=2.170.0 google-auth>=2.40.2 google-auth-oauthlib>=1.2.2 mcp>=1.9.1 # or with uv: uv add google>=3.0.0 google-api-python-client>=2.170.0 google-auth>=2.40.2 google-auth-oauthlib>=1.2.2 mcp>=1.9.1

Test Authentication

python gmail_auth_test.py

This will open your browser for Gmail OAuth approval and save authentication tokens.

Usage

Add to Claude Desktop

Add the following to your Claude Desktop configuration file:

Windows: %APPDATA%\Claude\claude_desktop_config.json
Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

{ "mcpServers": { "gmail-analyzer": { "command": "python", "args": ["path/to/your/main.py"], "env": {} } } }

Available Tools

test_connection

Test if the MCP server is working correctly.

fetch_and_analyze_gmail

Fetch emails from Gmail and analyze them automatically.

  • max_emails (int): Maximum emails to fetch (default: 5)
  • unread_only (bool): Only fetch unread emails (default: true)

analyze_emails

Analyze provided email content and categorize them.

  • emails (array): List of email contents to analyze

File Structure

├── main.py # MCP server implementation ├── gmail_analyzer.py # Standalone email analyzer ├── gmail_auth_test.py # Authentication testing script ├── credentials.json # Google OAuth credentials (you provide) ├── token.json # Generated authentication tokens ├── pyproject.toml # Project dependencies └── README.md # Documentation

Security & Privacy

OAuth2 Authentication

Uses secure OAuth2 for Gmail authentication

Read-Only Access

Only requests read-only access to Gmail (gmail.readonly scope)

Local Storage

Credentials are stored locally in token.json

Privacy First

No email content is stored permanently or sent to external services

Troubleshooting

"Credentials file not found"

Ensure credentials.json is in the same directory as the Python files

"Authentication failed"

Run python gmail_auth_test.py to reset authentication. Check that Gmail API is enabled in Google Cloud Console

"No emails found"

Try setting unread_only: false to fetch recent emails instead. Check your Gmail account has emails

Dependencies

google-api-python-client

Gmail API client for Python integration

google-auth

Google authentication library

google-auth-oauthlib

OAuth2 flow implementation

mcp

Model Context Protocol framework

Made with ❤️ by Lakshya Tripathi

Happy job hunting!