MCP 服务器

Gmail MCP Server

Connects to Gmail accounts to search emails, retrieve full email content, and parse receipts from services like Swiggy, Zomato, and Uber with read-only access.

README

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

Create a Google Cloud Project
- Go to the Google Cloud Console
- Create a new project (e.g., "Personal Assistant MCP")
Enable the Gmail API
- Navigate to "APIs & Services" > "Library"
- Search for "Gmail API" and click "Enable"
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)
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

Clone or download this repository
Navigate to the project directory
```
cd gmail-mcp-server
```
Create a virtual environment
```
python -m venv venv
```

Activate the virtual environment

Windows:
```
venv\Scripts\activate
```
Mac/Linux:
```
source venv/bin/activate
```

Install dependencies
```
pip install -r requirements.txt
```
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

Run the server for the first time
```
python src/server.py
```
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)
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