# Gmail MCP Server
A Model Context Protocol (MCP) server that provides Gmail integration for AI assistants. This server allows AI assistants to read unread emails, classify them, create draft replies, and save drafts to Gmail.
## Features
- **Get Unread Emails**: Retrieve the latest unread emails from your inbox
- **Classify Emails**: Automatically categorize emails as urgent, newsletter, work, personal, or unknown using HuggingFace transformers (BART-large-MNLI) with AI fallback for low-confidence predictions
- **Create Draft Replies**: Generate suggested email replies using AI (requires sampling support)
- **Save Drafts**: Save draft replies directly to Gmail
## Important: Client Compatibility
**Note about Sampling Support:** This server uses MCP's sampling feature for the `create_suggested_draft_reply` tool. Different MCP clients have different levels of support:
**Full Support (Sampling Enabled):**
- **GitHub Copilot** (VS Code extension) - All tools work including AI-powered draft replies
- Other clients listed at https://modelcontextprotocol.io/clients with sampling support
**Limited Support (No Sampling):**
- **Claude Desktop** - `get_unread_emails` and `save_draft_reply_to_gmail` work, but `create_suggested_draft_reply` will not function
Email classification uses HuggingFace transformers with AI fallback for low-confidence predictions (< 0.7) and works in all clients.
## Prerequisites
1. **Node.js** (v18 or higher)
2. **Google Cloud Project** with Gmail API enabled
3. **OAuth 2.0 credentials** from Google Cloud Console
### Setting up Google 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" and enable it
4. Create OAuth 2.0 credentials:
- Go to "APIs & Services" > "Credentials"
- Click "Create Credentials" > "OAuth client ID"
- Choose "Desktop app" as the application type
- **Important**: Add `http://localhost` to "Authorized redirect URIs"
- Download the credentials JSON file
5. Save the downloaded file as `secrets/google-credentials.json` in this project
## Installation
1. Clone this repository
2. Install dependencies:
```bash
npm install
```
3. Build the project:
```bash
npm run build
```
4. Create a `secrets` directory and add your `google-credentials.json` file
## Configuration
### For Claude Desktop and GitHub Copilot
Add to your Claude Desktop configuration file:
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Linux**: `~/.config/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"gmail": {
"command": "node",
"args": ["/absolute/path/to/gmail-mcp-server/dist/index.js"]
}
}
}
```
**Note**: Replace `/absolute/path/to/gmail-mcp-server` with the actual path to your cloned repository.
**GitHub Copilot** can also access MCP servers configured in the Claude Desktop config file, so this single configuration works for both tools.
## Demo & Examples
This server has been tested with both GitHub Copilot and Claude Desktop. See the [`screen-shots`](./screen-shots) folder for working examples:
### GitHub Copilot (Full Support with Sampling)
Shows all tools working including AI-powered draft generation.
- See examples in [`screen-shots/copilot-sampling/`](./screen-shots/copilot-sampling/)
### Claude Desktop (Limited Support - No Sampling)
Shows `get_unread_emails` and `save_draft_reply_to_gmail` working. The `create_suggested_draft_reply` tool does not work due to lack of sampling support.
- See examples in [`screen-shots/claude-desktop/`](./screen-shots/claude-desktop/)
**Example Prompts:**
- "Get my last 10 unread emails"
- "Create a professional draft reply to the email from [sender] saying I'll review it tomorrow"
- "Save this draft reply to gmail"
## Gmail Authorization
When you first start the server, it will automatically handle authorization:
1. The server will detect that you're not authorized
2. Your default browser will open automatically to Google's authorization page
3. Sign in with your Google account and authorize the application
4. The browser will show "Authorization successful! You can close this window."
5. The server will automatically save the token
You won't need to authorize again unless you revoke access or delete `secrets/token.json`.
## Available Tools
### `get_unread_emails`
Retrieves the latest unread emails from your Gmail inbox. **Emails are automatically classified** into categories (urgent, newsletter, work, personal, or unknown).
**Parameters:**
- `numberOfEmails` (number, 1-100): Number of emails to retrieve
### `create_suggested_draft_reply`
Creates an AI-generated draft reply to an email.
**Parameters:**
- `email` (object): Email object to reply to
- `instructions` (string, optional): Additional instructions for the reply
### `save_draft_reply_to_gmail`
Saves a draft reply to Gmail as a threaded response.
**Parameters:**
- `draftEmail` (string): The draft email content
- `email` (object): The email object to reply to (contains threadId for threading)
## Development
Run the server in development mode:
```bash
npm run dev
```
