Gmail MCP Server

A Model Context Protocol (MCP) server that connects to your Gmail account to retrieve and parse email receipts from various services like Swiggy, Zomato, Uber, and more. This provides a robust alternative to using private APIs.

Features

• Email Search: Search emails using Gmail query syntax with flexible filters (sender, date range, subject, etc.)

• Full Email Content: Retrieve complete email content including body and metadata

• Receipt Parsing: Specialized parsers for:

  • Swiggy orders (with detailed item breakdown, prices, dates)

  • Future support planned for Zomato, Uber, Blinkit, and more

Prerequisites

• Python 3.8 or higher

• A Google Cloud account

• Gmail API enabled on your Google Cloud project

Setup Guide

Step 1: Google Cloud Console Setup

1. Create a Google Cloud Project

   • Go to the Google Cloud Console

   • Create a new project (e.g., "Personal Assistant MCP")

2. Enable the Gmail API

   • Navigate to "APIs & Services" > "Library"

   • Search for "Gmail API" and click "Enable"

3. Configure OAuth Consent Screen

   • Go to "APIs & Services" > "OAuth consent screen"

   • Choose "External" user type (or "Internal" if you have Google Workspace)

   • Fill in required fields:

     • App name: e.g., "Gmail MCP Server"

     • User support email: your email

     • Developer contact information: your email

   • Click "Save and Continue"

   • Add the scope: https://www.googleapis.com/auth/gmail.readonly

   • Add your email address as a Test User (critical for external apps)

4. Create OAuth 2.0 Credentials

   • Go to "APIs & Services" > "Credentials"

   • Click "Create Credentials" > "OAuth client ID"

   • Application type: Desktop app

   • Name: "Gmail MCP Client"

   • Click "Create"

   • Download the JSON file and save it as credentials.json in the gmail-mcp-server directory

Step 2: Local Installation

1. Clone or download this repository

2. Navigate to the project directory

   cd gmail-mcp-server

3. Create a virtual environment

   python -m venv venv

4. Activate the virtual environment

   • Windows:

     venv\Scripts\activate

   • Mac/Linux:

     source venv/bin/activate

5. Install dependencies

   pip install -r requirements.txt

6. Copy your credentials file

   • Ensure credentials.json (downloaded from Google Cloud Console) is in the root of the gmail-mcp-server directory

   • You can use credentials.json.example as a reference for the expected structure

Step 3: First Run & Authentication

1. Run the server for the first time

   python src/server.py

2. Authenticate with Google

   • A browser window will automatically open

   • Sign in to your Google account

   • Grant the requested permissions (read-only Gmail access)

   • After successful authentication, a token.json file will be created

   • This token will be used for future runs (no need to re-authenticate)

3. Verify the server is running

   • You should see log output indicating the MCP server is ready

Configuration for MCP Clients

VS Code Configuration

Add this to your VS Code settings.json or MCP configuration file:

Important: Replace path/to/gmail-mcp-server with the absolute path to your installation directory.

Claude Desktop Configuration

Add this to your Claude Desktop MCP configuration file (claude_desktop_config.json):

Note: Ensure the Python executable is from your virtual environment, or activate the virtual environment before launching the MCP client.

Available Tools

1. search_emails

Search for emails with flexible filters.

Parameters:

• query (optional): General Gmail search query

• sender (optional): Filter by sender (e.g., "swiggy", "uber")

• recipient (optional): Filter by recipient

• subject (optional): Filter by subject line

• start_date (optional): Start date in common formats (e.g., "2024-01-01", "last week")

• end_date (optional): End date (exclusive)

• max_results (optional): Maximum number of emails to return (default: 10)

Returns: List of emails with ID, subject, sender, date, and snippet

2. get_email_content

Retrieve full content of a specific email.

Parameters:

• email_id (required): Gmail message ID from search results

Returns: Complete email content including body, headers, and metadata

3. get_swiggy_orders

Fetch and parse Swiggy order receipts.

Parameters:

• start_date (optional): Filter orders after this date (inclusive)

• end_date (optional): Filter orders before this date (exclusive)

• limit (optional): Maximum number of orders to return

Returns: Parsed order data with items, prices, dates, and order details

Security & Privacy

• Credentials: Your credentials.json and token.json files contain sensitive authentication data and are excluded from version control via .gitignore

• Read-Only Access: This server only requests read-only Gmail permissions

• Local Processing: All email parsing happens locally on your machine

• No Data Storage: Email data is not stored persistently by this server

Troubleshooting

"credentials.json not found"

• Ensure you've downloaded the OAuth client credentials from Google Cloud Console

• Place the file in the root directory of this project

• Rename it to exactly credentials.json

Authentication issues

• Delete token.json and re-run the server to re-authenticate

• Ensure your email is added as a Test User in the OAuth consent screen

• Check that the Gmail API is enabled in your Google Cloud project

Import errors

• Ensure your virtual environment is activated

• Reinstall dependencies: pip install -r requirements.txt

Server not connecting to VS Code/Claude

• Verify the absolute path in your MCP configuration

• Ensure Python is accessible from the command line

• Check that the cwd points to the correct directory

• Review logs for any startup errors

Development

To modify or extend this server:

1. The main server logic is in src/server.py

2. Authentication handling is in src/auth.py

3. Add new receipt parsers by following the Swiggy parser pattern

4. Submit pull requests for new features or bug fixes

License

MIT License - see LICENSE file for details

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests for:

• New receipt parsers (Zomato, Uber, Blinkit, etc.)

• Bug fixes

• Documentation improvements

• Feature enhancements