# Gmail MCP Server
A comprehensive Model Context Protocol (MCP) server for Gmail, providing 24 tools for full email management including sending, receiving, labels, filters, attachments, and batch operations.
## Features
- **24 Gmail Tools**: Full email operations, label management, filters, batch operations, and attachments
- **Multi-Account Support**: Manage multiple Gmail accounts with `--account` flag
- **OAuth Authentication**: Secure authentication with automatic token refresh
- **Attachment Support**: Download and send attachments
- **Batch Operations**: Efficiently modify or delete up to 1000 emails at once
- **Filter Templates**: Pre-built filter templates for common use cases
- **MCP Resources**: Access messages, threads, and labels via URI
## Prerequisites
- Node.js 18+
- A Google Cloud Project with Gmail API enabled
- OAuth 2.0 credentials (Desktop app type)
## Setup
### 1. Create Google Cloud OAuth Credentials
1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Create a new project or select an existing one
3. Enable the **Gmail API**:
- Navigate to "APIs & Services" > "Library"
- Search for "Gmail API"
- Click "Enable"
4. Create OAuth credentials:
- Go to "APIs & Services" > "Credentials"
- Click "Create Credentials" > "OAuth Client ID"
- If prompted, configure the OAuth consent screen:
- Choose "External" user type (or "Internal" for Workspace)
- Fill in required fields (app name, user support email, developer email)
- Add scopes: `gmail.modify` and `gmail.settings.basic`
- Add your email as a test user
- Select "Desktop app" as the application type
- Name it (e.g., "Gmail MCP")
- Click "Create"
5. Download the JSON credentials file
### 2. Install and Configure
```bash
# Clone or download the project
cd gmail-mcp
# Install dependencies
npm install
# Build the project
npm run build
# Create config directory and save credentials
mkdir -p ~/.gmail-mcp
cp /path/to/downloaded/credentials.json ~/.gmail-mcp/credentials.json
# Authenticate (for a single account)
node dist/index.js auth
# Or authenticate with a named account (for multi-account support)
node dist/index.js auth --account work
node dist/index.js auth --account personal
```
The auth command will:
1. Open your browser to Google's OAuth consent page
2. Ask you to authorize the application
3. Save the tokens to `~/.gmail-mcp/tokens/<account>.json`
To list authenticated accounts:
```bash
node dist/index.js list
```
### 3. Add to Claude Code
For a single account:
```bash
claude mcp add gmail -- node /path/to/gmail-mcp/dist/index.js
```
For multiple accounts, add each with its own name:
```bash
claude mcp add gmail-work -- node /path/to/gmail-mcp/dist/index.js --account work
claude mcp add gmail-personal -- node /path/to/gmail-mcp/dist/index.js --account personal
```
Or add manually to your Claude Code MCP settings:
```json
{
"mcpServers": {
"gmail-work": {
"command": "node",
"args": ["/path/to/gmail-mcp/dist/index.js", "--account", "work"]
},
"gmail-personal": {
"command": "node",
"args": ["/path/to/gmail-mcp/dist/index.js", "--account", "personal"]
}
}
}
```
## Available Tools
### Email Operations (7 tools)
| Tool | Description |
|------|-------------|
| `search_emails` | Search with Gmail query syntax, pagination |
| `read_email` | Full message with headers, body, attachment info |
| `send_email` | Send with to/cc/bcc, attachments, threading |
| `draft_email` | Create draft without sending |
| `delete_email` | Trash or permanent delete |
| `modify_email` | Add/remove labels from message |
| `get_thread` | Get full conversation thread |
### Label Management (6 tools)
| Tool | Description |
|------|-------------|
| `list_labels` | All labels (system + user) |
| `create_label` | Create with color, visibility |
| `update_label` | Rename, change settings |
| `delete_label` | Remove custom label |
| `get_or_create_label` | Idempotent label creation |
| `get_label` | Get single label details |
### Filter Management (5 tools)
| Tool | Description |
|------|-------------|
| `list_filters` | All Gmail filters |
| `get_filter` | Single filter details |
| `create_filter` | Custom criteria + actions |
| `delete_filter` | Remove filter |
| `create_filter_from_template` | Preset templates |
### Batch Operations (2 tools)
| Tool | Description |
|------|-------------|
| `batch_modify_emails` | Bulk add/remove labels (50 at a time) |
| `batch_delete_emails` | Bulk delete with fallback |
### Attachments (2 tools)
| Tool | Description |
|------|-------------|
| `download_attachment` | Save to local filesystem |
| `list_attachments` | Get attachment metadata for message |
### Utilities (2 tools)
| Tool | Description |
|------|-------------|
| `get_profile` | User email address, history ID |
| `get_quota` | Storage usage info |
## Resources
| Resource | URI Pattern |
|----------|-------------|
| Message | `gmail://messages/{messageId}` |
| Thread | `gmail://threads/{threadId}` |
| Label | `gmail://labels/{labelId}` |
## Usage Examples
### Search for unread emails
```
Search my Gmail for unread emails from the last week
```
### Read a specific email
```
Read the email with ID 18abc123def
```
### Send an email
```
Send an email to john@example.com with subject "Hello" and body "Hi John, how are you?"
```
### Create a filter
```
Create a Gmail filter that labels all emails from newsletter@example.com with "Newsletters"
```
### Batch operations
```
Move all emails matching "is:unread older_than:30d" to trash
```
## OAuth Scopes
The server uses these scopes:
- `gmail.modify` - Read, compose, send, and modify emails and labels
- `gmail.settings.basic` - Manage mail filters
## File Structure
```
gmail-mcp/
├── src/
│ ├── index.ts # CLI entry point
│ ├── server.ts # MCP server setup
│ ├── gmail/
│ │ ├── auth.ts # OAuth flow
│ │ ├── client.ts # Gmail API wrapper
│ │ ├── mime.ts # MIME parsing/encoding
│ │ └── types.ts # Type definitions
│ ├── tools/
│ │ ├── index.ts # Tool registration
│ │ ├── emails.ts # Email operations
│ │ ├── labels.ts # Label management
│ │ ├── filters.ts # Filter management
│ │ ├── batch.ts # Batch operations
│ │ └── attachments.ts # Attachment handling
│ ├── resources/
│ │ └── index.ts # MCP resources
│ └── schemas/
│ └── index.ts # Zod schemas
├── package.json
├── tsconfig.json
└── README.md
```
## Security
- Credentials stored in `~/.gmail-mcp/` with restricted permissions (0600)
- Per-account tokens stored in `~/.gmail-mcp/tokens/`
- Tokens automatically refresh when expired
- OAuth callback only on localhost
- No external telemetry or data collection
## Troubleshooting
### "Not authenticated" error
Run `node dist/index.js auth --account <name>` to authenticate.
### "Permission denied" error
Ensure your OAuth credentials have the correct scopes and the Gmail API is enabled.
### Token refresh fails
Delete `~/.gmail-mcp/tokens/<account>.json` and run auth again.
### Port 3000 in use
The OAuth callback requires port 3000. Close any applications using this port.
## License
MIT
