# 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](https://console.cloud.google.com/)
- 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**
```bash
cd gmail-mcp-server
```
3. **Create a virtual environment**
```bash
python -m venv venv
```
4. **Activate the virtual environment**
- Windows:
```bash
venv\Scripts\activate
```
- Mac/Linux:
```bash
source venv/bin/activate
```
5. **Install dependencies**
```bash
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**
```bash
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:
```json
{
"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`):
```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
