[//]: # (Constants)
[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/S9kS2D5ueg
# 
Gmail Manager MCP
**๐งน Clean your inbox โข ๐ท๏ธ Organize with labels โข ๐๏ธ Bulk delete emails**
[](https://www.npmjs.com/package/@spark-apps/gmail-manager-mcp)
[](https://smithery.ai/server/@muammar-yacoob/gmail-manager-mcp)
[](LICENSE)
[](https://github.com/sponsors/muammar-yacoob)
[][issues-link]
[][stars-link]
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 |
## ๐ Quick Setup
### ๐ Prerequisites: Get Gmail Credentials ๐๏ธ
๐ Required before any installation
1. [Create New Project](https://console.cloud.google.com/projectcreate) ๐
2. [Enable Gmail API](https://console.cloud.google.com/apis/api/gmail.googleapis.com/metrics) ๐ง
3. Create [OAuth client ID](https://console.cloud.google.com/auth/clients) (Desktop app type) ๐
4. Download as `gcp-oauth.keys.json` ๐ฅ
5. Navigate to [Data access](https://console.cloud.google.com/auth/scopes) โ **Add or remove scopes** โ Enter: `https://mail.google.com/` ๐
6. Navigate to [Test users](https://console.cloud.google.com/auth/audience) โ Add your Google email ๐ค
**๐ Where to put `gcp-oauth.keys.json`:**
**For Windows users in WSL:**
```bash
# Copy from Windows to current directory
cp /mnt/c/Users/YourUsername/gcp-oauth.keys.json ./gcp-oauth.keys.json
```
**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
๐ฆ Install from npm registry (Easier โก)
```bash
npm i -g @spark-apps/gmail-manager-mcp
```
---
๐ Clone and build locally (Safer ๐ก๏ธ)
```bash
git clone https://github.com/muammar-yacoob/GMail-Manager-MCP.git
cd GMail-Manager-MCP
npm install
```
---
## ๐ป Terminal Usage
๐ฅ๏ธ Quick Commands
```bash
# Install globally
npm i -g @spark-apps/gmail-manager-mcp
# Setup authentication (run this first)
npx @spark-apps/gmail-manager-mcp@latest auth
# Test MCP server (for debugging)
npx @modelcontextprotocol/inspector npx @spark-apps/gmail-manager-mcp@latest
```
---
## โ๏ธ 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:**
```json
{
"mcpServers": {
"gmail-manager": {
"command": "npx", "args": ["@spark-apps/gmail-manager-mcp@latest"],
"env": { "GMAIL_OAUTH_PATH": "C:\\path\\to\\gcp-oauth.keys.json" }
}
}
}
```
**For Local Development:**
```json
{
"mcpServers": {
"gmail-manager": {
"command": "node", "args": ["C:\\path\\to\\GMail-Manager-MCP\\dist\\index.js"]
}
}
}
```
## ๐ ๏ธ Available Tools
๐ง View All Available Tools
| Tool
| Description
|
|:------|:-------------|
|  | Authenticate Gmail access via web browser |
|  | Search emails using Gmail query syntax |
|  | Read the full content of an email |
|  | Create a draft reply to an email with a smart, context-aware response |
|  | List all Gmail labels |
|  | Create a new Gmail label |
|  | Apply a label to an email |
|  | Apply labels to multiple emails |
|  | Remove a label from an email |
|  | Delete a Gmail label |
|  | Permanently delete an email |
|  | Delete multiple emails at once |
## ๐ฌ Example Commands
๐งน Quick Cleanup
- *"Delete all promotional emails from last 30 days"*
- *"Delete all unread newsletters older than 1 week"*
- *"Delete all 'no-reply' emails from last 3 months"*
- *"Delete all LinkedIn notification emails"*
- *"Delete all password reset emails older than 1 month"*
- *"Delete redundant email chains where I'm CC'd"*
โก Smart Actions
- *"Summarize email with subject: 'last boring meeting'"*
- *"Summarize all emails about 'project deadline'"*
- *"Reply to email about 'project update' saying 'Got it, thanks!'"*
- *"Label all emails from my bank as 'Finance'"*
- *"Create 'Travel' label and move all booking confirmations"*
- *"Find emails with attachments larger than 5MB"*
๐ Inbox Insights
- *"Show me who sends me the most emails"*
- *"Find all unread emails older than 1 week"*
- *"Show my busiest email days this month"*
- *"Find emails I starred but never replied to"*
---
## ๐ฑ Support & Contributions
โญ **Star the repo** & I power up like Mario ๐
โ **Devs run on coffee** - [Buy me one?][coffee-link]
๐ฐ **Crypto tips welcome** - [Tip in crypto](https://tip.md/muammar-yacoob)
๐ค **Contributions are welcome** - [๐ด Fork][fork-link], improve, PR!
๐ฅ **Need help?** 
[Setup Tutorial][vid-link] โข 
[Join Discord][discord-link]
## ๐ Sponsor
Your support helps maintain and improve the tool. please consider [sponsoring the project][stars-link].
---
**Made with โค๏ธ for MCP** โข [Privacy Policy](PRIVACY.md) โข [Terms of Service](TERMS.md)