svarun115/gmail-mcp-server

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:

{
  "mcpServers": {
    "gmail": {
      "command": "python",
      "args": [
        "path/to/gmail-mcp-server/src/server.py"
      ],
      "cwd": "path/to/gmail-mcp-server",
      "env": {}
    }
  }
}

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):

{
  "mcpServers": {
    "gmail": {
      "command": "python",
      "args": [
        "path/to/gmail-mcp-server/src/server.py"
      ],
      "cwd": "path/to/gmail-mcp-server"
    }
  }
}

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