# 📧 Gmail MCP Pro
> **A powerful Model Context Protocol (MCP) server for Gmail** — Read, send, reply, and manage emails directly from Claude Desktop or any MCP-compatible AI assistant.
[](https://opensource.org/licenses/MIT)
[]()
[]()
---
## ✨ What Makes This Special
**Gmail MCP Pro** lets AI assistants like Claude interact with your Gmail inbox naturally. No complex OAuth flows, no Google Cloud Console setup — just a simple app password and you're ready to go in under 5 minutes.
### 🎯 Key Features
| Feature | Description |
|---------|-------------|
| 📖 **Read Full Emails** | Get complete email content, not just snippets |
| 📤 **Send Emails** | Compose and send emails with CC/BCC support |
| 💬 **Threaded Replies** | Reply to emails while keeping conversation threads intact |
| 🧵 **View Conversations** | See all messages in an email thread |
| ✅ **Mark Read/Unread** | Manage your inbox state |
| 📎 **Download Attachments** | Extract attachments from emails |
| 🔍 **Search Inbox** | Find emails using Gmail search syntax |
---
## 🚀 Quick Start (5 Minutes)
### Step 1: Get a Gmail App Password
1. Go to [Google Account Security](https://myaccount.google.com/security)
2. Enable **2-Step Verification** (required)
3. Go to **App Passwords** (search "app passwords" in account settings)
4. Select **Mail** and your device
5. Click **Generate** → Copy the 16-character password
> ⚠️ **Important:** You need 2-Step Verification enabled to create app passwords.
### Step 2: Clone & Install
```bash
git clone https://github.com/GodotH/GMAIL-MCP-PLUS.git
cd GMAIL-MCP-PLUS
npm install
```
### Step 3: Configure Environment
Create a `.env` file in the project root:
```env
EMAIL_ADDRESS=your.email@gmail.com
EMAIL_PASSWORD=xxxx xxxx xxxx xxxx
IMAP_HOST=imap.gmail.com
IMAP_PORT=993
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
```
> Replace `xxxx xxxx xxxx xxxx` with your 16-character app password (spaces optional).
### Step 4: Build
```bash
npm run build
```
### Step 5: Add to Claude Desktop
Open your Claude Desktop config file:
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Linux:** `~/.config/Claude/claude_desktop_config.json`
Add this configuration:
```json
{
"mcpServers": {
"gmail": {
"command": "node",
"args": ["C:/path/to/GMAIL-MCP-PLUS/dist/index.js"],
"cwd": "C:/path/to/GMAIL-MCP-PLUS"
}
}
}
```
> 📝 Replace `C:/path/to/GMAIL-MCP-PLUS` with your actual path.
### Step 6: Restart Claude Desktop
Close and reopen Claude Desktop. You should now be able to interact with your Gmail!
---
## 📚 Available Tools
### 📋 listMessages
List recent messages from your inbox.
```
"Show me my last 10 emails"
```
**Parameters:**
- `count` (optional): Number of messages (1-100, default: 10)
---
### 🔍 findMessage
Search for emails using Gmail search syntax.
```
"Find emails from john@example.com about the project"
```
**Parameters:**
- `query` (required): Search query
**Supported search operators:**
- `from:sender@example.com`
- `to:recipient@example.com`
- `subject:keyword`
- `has:attachment`
- `is:unread`
- `after:2024/01/01`
- `before:2024/12/31`
---
### 📖 getMessage
Read the full content of a specific email.
```
"Read email ID 19"
```
**Parameters:**
- `id` (required): Message ID (from listMessages or findMessage)
**Returns:** Complete email with body, attachments info, and threading headers.
---
### ✉️ sendMessage
Send a new email.
```
"Send an email to jane@example.com with subject 'Meeting Tomorrow' saying 'Hi Jane, can we meet at 3pm?'"
```
**Parameters:**
- `to` (required): Recipient email
- `subject` (required): Email subject
- `body` (required): Message content
- `cc` (optional): CC recipient
- `bcc` (optional): BCC recipient
---
### 💬 replyToMessage
Reply to an existing email (maintains thread).
```
"Reply to email 19 saying 'Thanks for the information!'"
```
**Parameters:**
- `id` (required): Message ID to reply to
- `body` (required): Reply content
- `includeQuote` (optional): Include original message (default: true)
---
### 🧵 getThread
Get all messages in a conversation.
```
"Show me the full conversation for email 19"
```
**Parameters:**
- `id` (required): Any message ID in the thread
---
### ✅ markAsRead
Mark an email as read or unread.
```
"Mark email 19 as read"
```
**Parameters:**
- `id` (required): Message ID
- `read` (optional): true for read, false for unread (default: true)
---
### 📎 getAttachment
Download an attachment from an email.
```
"Download the first attachment from email 19"
```
**Parameters:**
- `messageId` (required): Message ID
- `attachmentIndex` (optional): Which attachment (0-based, default: 0)
- `maxSizeBytes` (optional): Size limit (default: 10MB, max: 25MB)
---
## 🔧 Configuration Options
### Environment Variables
| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `EMAIL_ADDRESS` | Yes | - | Your Gmail address |
| `EMAIL_PASSWORD` | Yes | - | Gmail App Password |
| `IMAP_HOST` | No | `imap.gmail.com` | IMAP server |
| `IMAP_PORT` | No | `993` | IMAP port |
| `SMTP_HOST` | No | `smtp.gmail.com` | SMTP server |
| `SMTP_PORT` | No | `587` | SMTP port |
### Other Email Providers
Gmail MCP Pro works with any email provider that supports IMAP/SMTP:
**Outlook/Hotmail:**
```env
IMAP_HOST=outlook.office365.com
IMAP_PORT=993
SMTP_HOST=smtp-mail.outlook.com
SMTP_PORT=587
```
**Yahoo:**
```env
IMAP_HOST=imap.mail.yahoo.com
IMAP_PORT=993
SMTP_HOST=smtp.mail.yahoo.com
SMTP_PORT=587
```
---
## 🐳 Docker Usage (Optional)
```bash
# Build
docker build -t gmail-mcp-pro .
# Run
docker run --rm -i --env-file .env gmail-mcp-pro
```
Or with docker-compose:
```bash
docker-compose up -d
```
---
## 🛠️ Development
```bash
# Install dependencies
npm install
# Development mode (with tsx)
npm run dev
# Watch for changes
npm run watch
# Build for production
npm run build
# Start production
npm start
```
---
## 🔒 Security Notes
- **App Passwords** are specific to your app and can be revoked anytime
- **Never share** your `.env` file or commit it to git
- The `.gitignore` already excludes `.env`
- App passwords don't give access to your Google account settings
- You can delete the app password anytime to revoke access
---
## ❓ Troubleshooting
### "Authentication failed"
- Ensure 2-Step Verification is enabled on your Google account
- Generate a new App Password (they can only be viewed once)
- Make sure you're using the App Password, not your regular password
### "Connection refused"
- Check if your firewall allows ports 993 (IMAP) and 587 (SMTP)
- Verify IMAP is enabled in Gmail settings: Settings → See all settings → Forwarding and POP/IMAP → Enable IMAP
### "Message not found"
- Message IDs change between sessions
- Use `listMessages` or `findMessage` to get current IDs
### Claude Desktop doesn't see the tools
- Verify the path in `claude_desktop_config.json` is correct
- Restart Claude Desktop completely (not just close the window)
- Check the path uses forward slashes or escaped backslashes
---
## 📝 Changelog
### v2.0.0 (Current)
- ✨ **NEW:** `getMessage` - Read full email content
- ✨ **NEW:** `replyToMessage` - Threaded replies
- ✨ **NEW:** `getThread` - View full conversations
- ✨ **NEW:** `markAsRead` - Mark emails read/unread
- ✨ **NEW:** `getAttachment` - Download attachments
- 🔧 Improved email parsing with mailparser
- 🔧 Better error handling
### v1.0.0 (Original)
- Basic `listMessages`, `findMessage`, `sendMessage`
---
## 🙏 Credits
This project is a fork of [Sallytion/Gmail-MCP](https://github.com/Sallytion/Gmail-MCP), extended with additional functionality for full email management.
---
## 📄 License
MIT License — feel free to use, modify, and distribute.
---
## 👤 Author
**Godot Huard**
- GitHub: [@GodotH](https://github.com/GodotH)
---
## 🤝 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
---
## ⭐ Star History
If you find this useful, please give it a star! It helps others discover the project.
