Gmail MCP Server
An MCP (Model Context Protocol) server that provides Gmail integration for AI assistants. Search emails, read messages, and download attachments directly from your Gmail account.
Features
- Search emails using Gmail's powerful search syntax (
from:,subject:,has:attachment, etc.) - Read full email content including body and attachment metadata
- Download attachments to your local filesystem
Quick Start
1. Set up Google Cloud credentials
- Go to Google Cloud Console
- Create a new project (or select existing)
- Enable the Gmail API
- Go to APIs & Services > Credentials
- Click Create Credentials > OAuth client ID
- Select Desktop app as application type
- Download the JSON file and save it:```bash
mkdir -p ~/.gmail-mcp
mv ~/Downloads/client_secret_*.json ~/.gmail-mcp/gcp-oauth.keys.json
### 2. First-time authorization
Run once to complete OAuth (opens browser):```bash
uvx mcp-gmail-reader
Backup & Recovery
After a fresh OS install or losing your machine, here's what to restore:
| File | Where | Backup? | Recovery |
|---|---|---|---|
~/.gmail-mcp/gcp-oauth.keys.json |
Local only | YES — password manager | Cannot regenerate without recreating GCP project |
~/.gmail-mcp/token.json |
Local only | No | Regenerated by running uvx mcp-gmail-reader once (browser flow) |
~/Documents/gmail-mcp/ (this repo) |
Git | No need — git clone |
git clone https://github.com/Maheidem/gmail-mcp.git |
| MCP registration | ~/.claude/settings.json |
No | Re-add the JSON snippet from "Claude Code (CLI)" section above |
Recovery checklist (5 minutes after a fresh machine)```bash
1. Clone the source
git clone https://github.com/Maheidem/gmail-mcp.git ~/Documents/gmail-mcp
2. Restore credentials from your password manager
mkdir -p ~/.gmail-mcp
(paste gcp-oauth.keys.json into ~/.gmail-mcp/)
3. Install + first-run authorization (opens browser)
uvx mcp-gmail-reader
4. Re-register in Claude Code (see "Claude Code (CLI)" section below)
The OAuth credentials JSON is the only thing that **cannot** be recovered without doing the full Google Cloud Console setup again. Back it up.
---
## Setup by AI Tool
### Claude Desktop
Add to your config file:
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json````json
{
"mcpServers": {
"gmail": {
"command": "uvx",
"args": ["mcp-gmail-reader"]
}
}
}
Claude Code (CLI)
Add to your MCP settings (~/.claude/settings.json or project .mcp.json):```json
{
"mcpServers": {
"gmail": {
"command": "uvx",
"args": ["mcp-gmail-reader"]
}
}
}
### Cursor
Add to Cursor's MCP config (Settings > MCP Servers):```json
{
"gmail": {
"command": "uvx",
"args": ["mcp-gmail-reader"]
}
}
Windsurf
Add to ~/.codeium/windsurf/mcp_config.json:```json
{
"mcpServers": {
"gmail": {
"command": "uvx",
"args": ["mcp-gmail-reader"]
}
}
}
### VS Code + Continue
Add to Continue's config (`~/.continue/config.json`):```json
{
"experimental": {
"modelContextProtocolServers": [
{
"transport": {
"type": "stdio",
"command": "uvx",
"args": ["mcp-gmail-reader"]
}
}
]
}
}
Zed
Add to Zed's settings (~/.config/zed/settings.json):```json
{
"context_servers": {
"gmail": {
"command": {
"path": "uvx",
"args": ["mcp-gmail-reader"]
}
}
}
}
### Custom credentials path
If your credentials are in a different location:```json
{
"mcpServers": {
"gmail": {
"command": "uvx",
"args": ["mcp-gmail-reader"],
"env": {
"GMAIL_CREDENTIALS_PATH": "/path/to/your/credentials.json"
}
}
}
}
Available Tools
search_emails
Search Gmail using Gmail search syntax.
Query examples:
- from:example@gmail.com - emails from specific sender
- subject:invoice - emails with subject containing "invoice"
- has:attachment - emails with attachments
- after:2024/01/01 - emails after date
- is:unread - unread emails
- label:important - emails with specific label
- in:inbox - emails in inbox
get_email
Get full email content by message ID (returned from search_emails).
Returns: id, from, to, subject, date, body, attachments list
download_attachment
Download email attachment to specified path.
Parameters: message_id, attachment_id, save_path
Development```bash
git clone https://github.com/Maheidem/gmail-mcp.git
cd gmail-mcp
uv sync
Run server
uv run python -m gmail_mcp
Run with MCP inspector
uv run mcp dev src/gmail_mcp/server.py
```
Security Notes
- Only
gmail.readonlyscope is used - this server cannot send or modify emails - OAuth tokens are stored locally in
~/.gmail-mcp/token.json - Never commit credentials or tokens to version control
License
MIT
