📧 Gmail MCP Server
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
- Prerequisites
- Installation
- Configuration
- Google Cloud Setup
- OAuth2 Credentials
- Generate Refresh Token
- Usage
- Standalone Server
- Claude Desktop Integration
- Available Tools
- Examples
- Troubleshooting
- 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
- Clone the repository:```bash
git clone https://github.com/JaviEzpeleta/gmail-mcp-server.git
cd gmail-mcp-server
2. **Install dependencies:**```bash
npm install
- 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
- 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.
- 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
- 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
- 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
- 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 retrieveformat(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 addresssubject(string, required): Email subjectbody(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.
- Fork the repository
- Create your feature branch (
git checkout -b feature/AmazingFeature) - Commit your changes (
git commit -m 'Add some AmazingFeature') - Push to the branch (
git push origin feature/AmazingFeature) - Open a Pull Request
📄 License
This project is licensed under the MIT License - see the LICENSE file
for details.
🙏 Acknowledgments
- Google Gmail API for email
functionality - Model Context Protocol for the MCP
specification - Anthropic for Claude and MCP development
📞 Support
For issues, questions, or suggestions:
- Open an issue on
GitHub - Check existing issues for solutions
- Read the
Gmail API documentation
Made with ❤️ by Javi Ezpeleta
