# 📧 Gmail MCP Server
[](https://www.typescriptlang.org/)
[](https://modelcontextprotocol.org/)
[](https://developers.google.com/gmail/api)
[](LICENSE)
A powerful MCP (Model Context Protocol) server that enables AI assistants to
interact with Gmail through OAuth2 authentication **with safety-first design**.
Built with TypeScript and designed for seamless integration with Claude Desktop
and other MCP-compatible clients.
## 📑 Table of Contents
- [Features](#-features)
- [Prerequisites](#-prerequisites)
- [Installation](#-installation)
- [Configuration](#-configuration)
- [Google Cloud Setup](#1-google-cloud-console-setup)
- [OAuth2 Credentials](#2-create-oauth2-credentials)
- [Generate Refresh Token](#3-generate-refresh-token)
- [Usage](#-usage)
- [Standalone Server](#standalone-server)
- [Claude Desktop Integration](#claude-desktop-integration)
- [Available Tools](#-available-tools)
- [Examples](#-examples)
- [Troubleshooting](#-troubleshooting)
- [Development](#-development)
## ✨ Features
- 🛡️ **Safety First** - Draft-only mode by default prevents accidental email sends
- 📝 **Smart Drafts** - Create drafts for new emails and replies with custom content
- 📬 **List Emails** - Retrieve recent emails with advanced filtering options
- 📖 **Get Email Details** - Fetch complete email content including attachments info
- 🔍 **Search Emails** - Use Gmail's powerful search syntax to find specific emails
- ✉️ **Send Emails** - Direct sending (disabled by default, enable with caution)
- 🔐 **Secure OAuth2** - Industry-standard authentication with refresh token support
- 🎯 **Type-Safe** - Full TypeScript implementation with strict typing
- 🚀 **High Performance** - Optimized with parallel processing and smart caching
## 📋 Prerequisites
Before you begin, ensure you have:
- **Node.js** 18.0 or higher
- **npm** or **yarn** package manager
- **Google Account** with Gmail enabled
- **Google Cloud Console** access
- **Claude Desktop** (optional, for integration)
## 📦 Installation
1. **Clone the repository:**
```bash
git clone https://github.com/JaviEzpeleta/gmail-mcp-server.git
cd gmail-mcp-server
```
2. **Install dependencies:**
```bash
npm install
```
3. **Create environment file:**
```bash
cp .env.example .env
```
> **🛡️ Security Note**: By default, direct email sending is disabled for safety. The server will create drafts instead, which you can review and send manually from Gmail.
## ⚙️ Configuration
### 1. Google Cloud Console Setup
1. **Create or select a project:**
- Go to [Google Cloud Console](https://console.cloud.google.com/)
- Click on the project dropdown and select "New Project"
- Give your project a name (e.g., "Gmail MCP Server")
- Click "Create"
2. **Enable Gmail API:**
- In the sidebar, navigate to **APIs & Services** → **Library**
- Search for "Gmail API"
- Click on **Gmail API** from the results
- Click **Enable**
- Wait for the API to be enabled (usually takes a few seconds)
### 2. Create OAuth2 Credentials
1. **Configure OAuth consent screen:**
- Go to **APIs & Services** → **OAuth consent screen**
- Select "External" user type (unless you have a Google Workspace account)
- Fill in the required fields:
- App name: "Gmail MCP Server"
- User support email: Your email
- Developer contact: Your email
- Add scopes:
- `https://www.googleapis.com/auth/gmail.readonly`
- `https://www.googleapis.com/auth/gmail.send`
- `https://www.googleapis.com/auth/gmail.modify`
- Add test users (important!):
- Add your Gmail address and any other accounts you want to use
- Save and continue through all steps
2. **Create OAuth client:**
- Go to **APIs & Services** → **Credentials**
- Click **+ CREATE CREDENTIALS** → **OAuth client ID**
- Application type: **Web application** ⚠️ (NOT Desktop app)
- Name: "Gmail MCP Web Client"
- **Configure Authorized redirect URIs:**
- Click **+ ADD URI**
- Add: `http://localhost:8765/oauth2callback` (default port)
- If you plan to use a custom port, add: `http://localhost:YOUR_PORT/oauth2callback`
- Click **Create**
- **Download the credentials** (you'll see a download button or JSON option)
- Save the `client_id` and `client_secret` from the downloaded file
> **⚠️ Important**: Desktop app type doesn't allow custom redirect URIs, but we need `localhost:PORT/oauth2callback` for the OAuth flow to work. That's why we use **Web application** instead.
### 3. Generate Refresh Token
1. **Add credentials to .env:**
```bash
GMAIL_CLIENT_ID=your_client_id_here
GMAIL_CLIENT_SECRET=your_client_secret_here
GMAIL_REFRESH_TOKEN=
# Security: Keep this false unless you need direct sending
GMAIL_ALLOW_DIRECT_SEND=false
# OAuth setup port (must match the redirect URI you configured above)
OAUTH_REDIRECT_PORT=8765
```
> **💡 Port Configuration**: The `OAUTH_REDIRECT_PORT` must match the port you configured in the Google Cloud Console redirect URI. If you used `http://localhost:8765/oauth2callback`, keep it as 8765. If you used a different port, update this value accordingly.
2. **Run the setup script:**
```bash
npm run setup
# or
npm run dev src/get-refresh-token-desktop.ts
```
3. **Authorize the application:**
- A browser window will open automatically
- Sign in with your Google account
- Grant all requested permissions
- You'll be redirected to a success page
4. **Save the refresh token:**
- The terminal will display your refresh token
- Copy the complete `GMAIL_REFRESH_TOKEN` value
- Add it to your `.env` file
## 🚀 Usage
### Standalone Server
1. **Build the project:**
```bash
npm run build
```
2. **Start the server:**
```bash
npm start
```
The server will start and listen for MCP commands via stdio.
### Claude Desktop Integration
1. **Build the project first:**
```bash
npm run build
```
2. **Locate Claude Desktop config:**
- **macOS**:
`~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`
3. **Edit the configuration file:**
```json
{
"mcpServers": {
"gmail": {
"command": "node",
"args": ["/absolute/path/to/gmail-mcp-server/dist/index.js"],
"env": {
"GMAIL_CLIENT_ID": "your_client_id",
"GMAIL_CLIENT_SECRET": "your_client_secret",
"GMAIL_REFRESH_TOKEN": "your_refresh_token",
"GMAIL_ALLOW_DIRECT_SEND": "false"
}
}
}
}
```
4. **Restart Claude Desktop**
5. **Verify the connection:**
- Open Claude Desktop
- Look for the 🔌 icon indicating MCP connection
- Try: "List my recent emails"
## 🛠️ Available Tools
> **🛡️ Safety Notice**: Tools marked with 🛡️ create drafts by default for your safety. Direct sending tools marked with 🚨 are disabled by default.
### 📬 list_emails
List recent emails with optional filtering.
**Parameters:**
- `maxResults` (number, 1-100): Maximum emails to return (default: 10)
- `query` (string): Gmail search query (e.g., "is:unread")
- `includeSpamTrash` (boolean): Include SPAM/TRASH folders (default: false)
**Example:**
```
List my 5 most recent unread emails
```
### 📖 get_email_details
Get complete details and content of a specific email.
**Parameters:**
- `emailId` (string, required): The email ID to retrieve
- `format` (string): Level of detail - "full", "minimal", or "metadata"
(default: "full")
**Example:**
```
Get the full content of email ID 18abc123def
```
### 🛡️ create_draft
Create an email draft with optional CC/BCC recipients (recommended for AI assistants).
**Parameters:**
- `to` (string, required): Recipient email address
- `subject` (string, required): Email subject
- `body` (string, required): Email body (plain text or HTML)
- `cc` (string): CC recipients (comma-separated)
- `bcc` (string): BCC recipients (comma-separated)
**Example:**
```
Create a draft email to john@example.com with subject "Meeting Tomorrow" and body "Let's meet at 10 AM"
```
### 🚨 send_email (Disabled by Default)
Send an email directly with optional CC/BCC recipients.
**⚠️ Security Warning**: This tool is disabled by default. Set `GMAIL_ALLOW_DIRECT_SEND=true` to enable.
**Parameters:**
- `to` (string, required): Recipient email address
- `subject` (string, required): Email subject
- `body` (string, required): Email body (plain text or HTML)
- `cc` (string): CC recipients (comma-separated)
- `bcc` (string): BCC recipients (comma-separated)
**Example:**
```
Send an email to john@example.com with subject "Meeting Tomorrow" and body "Let's meet at 10 AM"
```
### 🔍 search_emails
Search emails using Gmail's advanced search syntax.
**Parameters:**
- `query` (string, required): Gmail search query
- `maxResults` (number, 1-100): Maximum results (default: 10)
- `includeSpamTrash` (boolean): Include SPAM/TRASH (default: false)
**Example Gmail search queries:**
- `from:user@example.com` - Emails from a specific sender
- `subject:"important meeting"` - Emails with exact phrase in subject
- `has:attachment` - Emails with attachments
- `is:unread` - Unread emails
- `newer_than:2d` - Emails from last 2 days
- `label:work` - Emails with specific label
### 🛡️ find_and_draft_reply
Find the latest email from a sender and create a draft reply with optional custom content.
**Parameters:**
- `senderName` (string, required): Sender name or email address
- `replyBody` (string, optional): Custom reply content (template used if not provided)
**Example:**
```
Create a draft reply to the latest email from John Smith saying "Thanks for your message. I'll get back to you soon."
```
## 📚 Examples
### Basic Usage Examples
**List recent emails:**
```
Show me my 10 most recent emails
```
**Search for specific emails:**
```
Search for emails from alice@example.com with attachments
```
**Create a draft email:**
```
Create a draft email to bob@example.com saying "Thanks for your help!"
```
**Create a draft reply:**
```
Draft a reply to the latest email from support@company.com
```
### Advanced Usage Examples
**Complex search:**
```
Find all unread emails from the last week with "invoice" in the subject
```
**Draft with CC:**
```
Create a draft email to team@company.com with CC to manager@company.com about the project update
```
**Get email details:**
```
Show me the full content of the most recent email from my boss
```
## 🔧 Troubleshooting
### Common Issues and Solutions
#### ❌ Error: Missing required environment variables
**Solution:** Ensure all required environment variables are set in your `.env` file:
- `GMAIL_CLIENT_ID`
- `GMAIL_CLIENT_SECRET`
- `GMAIL_REFRESH_TOKEN`
- `GMAIL_ALLOW_DIRECT_SEND` (optional, defaults to `false`)
- `OAUTH_REDIRECT_PORT` (optional, defaults to `8765`)
#### ❌ Error: redirect_uri_mismatch
**Problem:** OAuth setup fails with "The redirect URI in the request does not match the ones authorized for the OAuth client."
**Solution:**
1. Go to Google Cloud Console → APIs & Services → Credentials
2. Click on your OAuth client
3. In "Authorized redirect URIs", ensure you have: `http://localhost:8765/oauth2callback`
4. If using a custom port, add: `http://localhost:YOUR_PORT/oauth2callback`
5. Make sure your `.env` file has the matching `OAUTH_REDIRECT_PORT=8765`
6. **Important**: OAuth client must be **Web application** type, not Desktop app
> This error commonly occurs when following old documentation that suggests using "Desktop app" type, which doesn't support custom redirect URIs.
#### 🛡️ Security: Direct email sending is disabled
**This is normal and safe behavior.** By default, the server creates drafts instead of sending emails directly.
**Solutions:**
- **Recommended**: Use `create_draft` tool instead of `send_email`
- **Alternative**: Set `GMAIL_ALLOW_DIRECT_SEND=true` in your `.env` file (not recommended for AI assistants)
#### ❌ Error 403: access_denied
**Solution:**
1. Go to Google Cloud Console → OAuth consent screen
2. Add your email as a test user
3. Re-run the token generation process
#### ❌ Error: invalid_grant
**Solution:** Your refresh token has expired or is invalid
1. Delete the old refresh token from `.env`
2. Run `npm run setup` again
3. Complete the authorization flow
4. Update `.env` with the new token
#### ❌ Gmail API not enabled
**Solution:**
1. Go to Google Cloud Console
2. Navigate to APIs & Services → Library
3. Search for "Gmail API"
4. Click Enable
#### ❌ Claude Desktop doesn't show the MCP server
**Solution:**
1. Verify the config file path is correct
2. Ensure all paths in the config are absolute paths
3. Check that the built files exist in `dist/`
4. Restart Claude Desktop completely
5. Check Claude Desktop logs for errors
#### ❌ Rate limit exceeded
**Solution:**
- Gmail API has quotas (250 quota units per user per second)
- Implement exponential backoff for retries
- Reduce the number of parallel requests
## 🔒 Security Guidelines
### Draft-First Approach
This server implements a **safety-first design** to prevent accidental email sends:
- **Default behavior**: Creates drafts that require manual review
- **Protection**: `send_email` tool is disabled by default
- **User control**: Explicit environment variable required for direct sending
### Recommended Usage
✅ **Safe for AI assistants:**
- `create_draft` - Creates email drafts
- `find_and_draft_reply` - Creates reply drafts
- `list_emails`, `search_emails`, `get_email_details` - Read-only operations
⚠️ **Use with caution:**
- `send_email` - Only enable if you fully trust the AI assistant and understand the risks
### Best Practices
1. **Keep `GMAIL_ALLOW_DIRECT_SEND=false`** unless absolutely necessary
2. **Review all drafts** before sending manually from Gmail
3. **Test thoroughly** in a safe environment before production use
4. **Monitor usage** and check for unexpected behavior
## 🔨 Development
### Available Scripts
```bash
# Development with hot reload
npm run dev
# Build TypeScript to JavaScript
npm run build
# Start production server
npm start
# Generate OAuth refresh token
npm run setup
# Run tests
npm test
# Lint code
npm run lint
```
### Project Structure
```
gmail-mcp-server/
├── src/
│ ├── index.ts # Main server implementation
│ └── get-refresh-token-desktop.ts # OAuth setup utility
├── dist/ # Compiled JavaScript (generated)
├── examples/ # Usage examples
├── docs/ # Additional documentation
├── .env.example # Environment variables template
├── tsconfig.json # TypeScript configuration
├── package.json # Project dependencies
└── README.md # This file
```
### Testing
Test the connection and basic functionality:
```bash
# Test Gmail connection
npm run dev test-gmail-connection.ts
# Test with MCP client
npm run dev test-list-emails.js
```
## 🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
for details.
## 🙏 Acknowledgments
- [Google Gmail API](https://developers.google.com/gmail/api) for email
functionality
- [Model Context Protocol](https://modelcontextprotocol.org/) for the MCP
specification
- [Anthropic](https://anthropic.com/) for Claude and MCP development
## 📞 Support
For issues, questions, or suggestions:
- Open an issue on
[GitHub](https://github.com/JaviEzpeleta/gmail-mcp-server/issues)
- Check existing issues for solutions
- Read the
[Gmail API documentation](https://developers.google.com/gmail/api/guides)
---
Made with ❤️ by [Javi Ezpeleta](https://github.com/JaviEzpeleta)
