<img src="public/images/trash-mail.png" alt="Gmail Manager" width="48" height="48" style="vertical-align: middle;"> Gmail Manager MCP

<div align="center">

🧹 Clean your inbox • 🏷️ Organize with labels • 🗑️ Bulk delete emails

<img src="public/images/meme.png" alt="Stop sending me unnecessary emails meme" width="400">

</div>

✨ What It Does

Gmail Manager MCP gives Claude Desktop direct access to your Gmail inbox, 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

🚀 Quick Setup

📋 Prerequisites: Get Gmail Credentials 🗝️

<details> <summary><strong>🔑 Required before any installation</strong></summary>

1. Create New Project 📁
2. Enable Gmail API 📧
3. Create OAuth client ID (Desktop app type) 🔐
4. Download as gcp-oauth.keys.json 📥
5. Navigate to Data access → Add or remove scopes → Enter: https://mail.google.com/ 🔓
6. Navigate to Test users → Add your Google email 👤

📁 Where to put gcp-oauth.keys.json:

• If using npm (npx): Place it in your home directory
  Windows: %USERPROFILE% • macOS/Linux: ~/
• If running locally from source: Place it in the project root (same folder as package.json)
• Or set a custom path: Define GMAIL_OAUTH_PATH in your Claude Desktop config to point to the file

</details>

---

📥 Installation

<details> <summary><strong>📦 Install from npm registry (Easier ⚡) </strong></summary>

npm i -g @spark-apps/gmail-manager-mcp

</details>

---

<details> <summary><strong>🏠 Clone and build locally (Safer 🛡️)</strong></summary>

git clone https://github.com/muammar-yacoob/GMail-Manager-MCP.git
cd GMail-Manager-MCP
npm install

</details>

</details>

---

⚙️ Configure Claude Desktop

<details> <summary><strong>🔧 Required for all installation methods</strong></summary>

Add to your Claude Desktop config file:

• %APPDATA%\\Claude\\claude_desktop_config.json
• ~/Library/Application Support/Claude/claude_desktop_config.json
• ~/.config/Claude/claude_desktop_config.json

📦 For NPM Install:

{
  "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:

{
  "mcpServers": {
    "gmail-manager": {
      "command": "node", "args": ["C:\\path\\to\\GMail-Manager-MCP\\dist\\index.js"]
    }
  }
}

</details>

🛠️ Available Tools

<details> <summary><strong>🔧 View All Available Tools</strong></summary>

Tool	Description
	Authenticate Gmail access via web browser
	Search emails using Gmail query syntax
	Read the full content of an email
	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

</details>

💬 Example Commands

<details> <summary><strong>🧹 Quick Cleanup</strong></summary>

• "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"

</details>

<details> <summary><strong>⚡ Smart Actions</strong></summary>

• "Summarize email with subject: 'last boring meeting'"
• "Summarize all emails about 'project deadline'"
• "Label all emails from my bank as 'Finance'"
• "Create 'Travel' label and move all booking confirmations"
• "Find emails with attachments larger than 5MB"

</details>

<details> <summary><strong>📊 Inbox Insights</strong></summary>

• "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"

</details>

---

🌱 Support & Contributions

⭐ Star the repo & I power up like Mario 🍄
☕ Devs run on coffee - Buy me one?
🤝 Contributions are welcome - 🍴 Fork, improve, PR!
🎥 Need help? <img src="https://img.icons8.com/color/20/youtube-play.png" alt="YouTube" style="vertical-align: middle;"> Setup Tutorial • <img src="https://img.icons8.com/color/20/discord--v2.png" alt="Discord" style="vertical-align: middle;"> Join Discord

💖 Sponsor

Your support helps maintain and improve the tool. please consider sponsoring the project.

---

<div align="center">

Made with ❤️ for Claude Desktop • Privacy Policy • Terms of Service

</div>