muammar-yacoob/GMail-Manager-MCP

[license-link]: ../../blob/main/LICENSE
[stars-link]: ../../stargazers
[vid-link]: https://www.youtube.com/shorts/CCbY_ETwFss
[website-link]: https://spark-games.co.uk
[coffee-link]: https://buymeacoffee.com/spark88
[bug-link]: ../../issues
[release-link]: ../../releases
[fork-link]: ../../fork
[privacy-link]: ./PRIVACY.md
[issues-link]: ../../issues
[discord-link]: https://discord.gg/dDnNNXSWJQ
Gmail Manager MCP
**🧹 Clean your inbox • 🏷️ Organize with labels • 🗑️ Bulk delete emails**
[ ][issues-link]
[ ][stars-link]
✨ What It Does
Gmail Manager MCP provides **direct access** to your Gmail inbox through the Model Context Protocol, allowing you to:
| Feature | Description |
|:---------|:-------------|
| | Find emails by sender, subject, date, or any Gmail query |
| | Get insights about your email patterns and volume |
| | Read the full content of an email |
| | Create and apply labels to categorize emails automatically |
| | Remove old newsletters, notifications, and spam efficiently |
| | List, search, create and update events, RSVP, and find times everyone is free |
| | Attach local files to drafts, download attachments, or file them into Drive |
> [!IMPORTANT]
> **Upgrading from a version before calendar or Drive support?** Google cannot add scopes to a token it has already issued, so your saved credentials keep working for mail while calendar calls and save_attachment_to_drive fail with a permissions error. Enable the Calendar and Drive APIs and add their scopes as below, then re-authenticate once:
>
> Running a local checkout instead of the published package? Re-authenticate with the build your client actually loads, or you will re-consent against whichever version npm is serving and see the same error:
>
🚀 Quick Setup
📋 Prerequisites: Get Gmail Credentials 🗝️
🔑 Required before any installation
1. Create New Project 📁
2. Enable all three APIs: Gmail 📧, Calendar 📅 and Drive 📁
3. Create OAuth client ID (Desktop app type) 🔐
4. Download as gcp-oauth.keys.json 📥
5. Navigate to Data access → **Add or remove scopes** → add **all three**: https://mail.google.com/, https://www.googleapis.com/auth/calendar and https://www.googleapis.com/auth/drive.file 🔓
6. Navigate to Test users → Add your Google email 👤
**📁 Where to put gcp-oauth.keys.json:**
**For Windows users in WSL:**
**General locations:**
- **Current directory**: ./gcp-oauth.keys.json (works everywhere)
- **Home directory**: ~/gcp-oauth.keys.json (for npx usage)
- **Custom path**: Set GMAIL_OAUTH_PATH environment variable
---
📥 Installation
**Claude Code**, one line, nothing to install first:
Add -s user to make it available in every project instead of just this one.
Then authorise your Google account once:
That needs an OAuth keys file. See Quick Setup above if you have not made one yet.
📦 Other clients, or a global install
The server runs straight from npm, so npx is enough for any MCP client (see Configure MCP Client for the JSON form):
Prefer it on your PATH as gmail-manager:
---
🏠 Clone and build locally (Safer 🛡️)
---
💻 Terminal Usage
🖥️ Quick Commands
---
⚙️ Configure MCP Client
🔧 Required for MCP client integration
Add to your MCP client config file (Claude Desktop example):
- Windows %APPDATA%\\Claude\\claude_desktop_config.json
- macOS ~/Library/Application Support/Claude/claude_desktop_config.json
- Linux ~/.config/Claude/claude_desktop_config.json
**📦 For NPM Install:**
**For Local Development:**
🛠️ Available Tools
🔧 View All Available Tools
📬 Reading
| Tool | Description |
|:-----|:------------|
| search_emails | Search using Gmail query syntax |
| read_email | Full content of one email |
| get_thread | Every message in a conversation, oldest first |
🧹 Cleaning up
| Tool | Description |
|:-----|:------------|
| trash_emails | Move to Trash, recoverable for 30 days. **Prefer this** |
| untrash_emails | Pull messages back out of Trash |
| archive_emails | Remove from inbox, keep everything else |
| mark_emails | Mark read or unread |