# Gmail MCP Server
A Model Context Protocol (MCP) server that provides Gmail access for Claude Code and other MCP-compatible clients.
## Features
- List emails from any folder (inbox, sent, unread, starred, etc.)
- Read full email content
- Send emails with automatic signature
- Reply to threads with proper threading headers
- Search using Gmail's query syntax
- Manage labels (star, archive, mark read/unread)
## Prerequisites
- Node.js 20 or higher
- A Google Cloud project with Gmail API enabled
- OAuth 2.0 credentials (Desktop app type)
## Setup
### 1. Create a Google Cloud Project
If you don't have one already:
```bash
gcloud projects create your-project-name --name="Your MCP Tools"
gcloud config set project your-project-name
gcloud services enable gmail.googleapis.com
```
### 2. Configure OAuth Consent Screen
1. Go to [Google Cloud Console - OAuth Consent](https://console.cloud.google.com/apis/credentials/consent)
2. Select **Internal** (for Google Workspace) or **External** (for personal Gmail)
3. Add these scopes:
- `https://www.googleapis.com/auth/gmail.readonly`
- `https://www.googleapis.com/auth/gmail.send`
- `https://www.googleapis.com/auth/gmail.modify`
### 3. Create OAuth Credentials
1. Go to [Google Cloud Console - Credentials](https://console.cloud.google.com/apis/credentials)
2. Click **Create Credentials** > **OAuth client ID**
3. Select **Desktop app** as the application type
4. Download the JSON file
5. Save it as `~/.mcp-gmail/credentials.json`
### 4. Install and Build
```bash
git clone https://github.com/brentwpeterson/mcp-gmail.git
cd mcp-gmail
npm install
npm run build
```
### 5. Authenticate
```bash
npm run auth
```
This opens a browser for Google OAuth. Approve the permissions, and tokens will be saved to `~/.mcp-gmail/token.json`.
### 6. Configure Your MCP Client
Add to your MCP configuration file (e.g., `.mcp.json` for Claude Code):
```json
{
"mcpServers": {
"gmail": {
"command": "node",
"args": ["/absolute/path/to/mcp-gmail/dist/index.js"]
}
}
}
```
Restart your MCP client to load the server.
## Available Tools
| Tool | Description |
|------|-------------|
| `gmail_list_emails` | List recent emails with optional folder and search query |
| `gmail_get_email` | Get full content of a specific email |
| `gmail_send_email` | Send a new email or reply to a thread |
| `gmail_search` | Search emails using Gmail query syntax |
| `gmail_get_thread` | Get all messages in a conversation |
| `gmail_modify_labels` | Add/remove labels (read, star, archive) |
| `gmail_list_labels` | List all available labels |
## Folder Options
The `gmail_list_emails` tool supports these folders:
| Folder | Description |
|--------|-------------|
| `inbox` (default) | Inbox emails |
| `sent` | Sent emails |
| `unread` | Unread inbox emails |
| `starred` | Starred emails |
| `important` | Important emails |
| `trash` | Deleted emails |
| `spam` | Spam folder |
| `all` | All emails (no filter) |
## Gmail Search Syntax
The `gmail_search` tool and `query` parameter support Gmail's search syntax:
- `from:user@example.com` - From specific sender
- `to:user@example.com` - To specific recipient
- `subject:meeting` - Subject contains word
- `is:unread` - Unread messages
- `is:starred` - Starred messages
- `has:attachment` - Has attachments
- `newer_than:2d` - Newer than 2 days
- `older_than:1w` - Older than 1 week
- `label:work` - Has specific label
Combine with spaces (AND) or `OR`: `from:boss@work.com is:unread`
## Configuration
Environment variables (optional):
| Variable | Description | Default |
|----------|-------------|---------|
| `GMAIL_CONFIG_DIR` | Config directory | `~/.mcp-gmail` |
| `GMAIL_CREDENTIALS_PATH` | Path to credentials.json | `~/.mcp-gmail/credentials.json` |
## How It Works
- **Signatures**: Automatically fetched from your Gmail "Send mail as" settings
- **Thread Replies**: Proper `In-Reply-To` and `References` headers for correct threading
- **Sender Name**: Uses your display name from Gmail settings
## Security
- OAuth tokens are stored locally in `~/.mcp-gmail/token.json`
- Credentials and tokens are never committed (see `.gitignore`)
- Only you can access your email through this server
- Tokens can be revoked at any time from [Google Account Permissions](https://myaccount.google.com/permissions)
## License
MIT
