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.jsonin thegmail-mcp-serverdirectory
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
- Windows:
-
Install dependencies
pip install -r requirements.txt -
Copy your credentials file
- Ensure
credentials.json(downloaded from Google Cloud Console) is in the root of thegmail-mcp-serverdirectory - You can use
credentials.json.exampleas a reference for the expected structure
- Ensure
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.jsonfile 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 querysender(optional): Filter by sender (e.g., "swiggy", "uber")recipient(optional): Filter by recipientsubject(optional): Filter by subject linestart_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.jsonandtoken.jsonfiles 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.jsonand 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
cwdpoints to the correct directory - Review logs for any startup errors
Development
To modify or extend this server:
- The main server logic is in
src/server.py - Authentication handling is in
src/auth.py - Add new receipt parsers by following the Swiggy parser pattern
- 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