GMail Manager MCP

[//]: # (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/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

[!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:

npx @spark-apps/gmail-manager-mcp@latest auth

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:

node /path/to/GMail-Manager-MCP/dist/index.js auth

🚀 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:

# 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

Claude Code, one line, nothing to install first:

claude mcp add gmail-manager -- npx -y @spark-apps/gmail-manager-mcp@latest

Add -s user to make it available in every project instead of just this one.

Then authorise your Google account once:

npx @spark-apps/gmail-manager-mcp@latest auth

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):

npx -y @spark-apps/gmail-manager-mcp@latest

Prefer it on your PATH as gmail-manager:

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

---

🏠 Clone and build locally (Safer 🛡️)

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

---

💻 Terminal Usage

🖥️ Quick Commands

# 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:

{
  "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"]
    }
  }
}

🛠️ Available Tools

🔧 View All Available Tools

📬 Reading

🧹 Cleaning up

🏷️ Labels

⚙️ Rules & unsubscribing

✍️ Drafts

Everything here writes to Drafts. Nothing is delivered. See Sending below.

Three things these do that are worth knowing about:

Every draft reports the recipient Gmail actually stored, read back from the saved message rather than echoed from the request. A wrong address is visible before anyone presses send, which is the only moment it can still be fixed.

A draft addressed only to yourself is called out. create_reply used to answer the From header unconditionally, so replying to your own sent mail resolved the recipient to your own address: the draft looked perfectly correct and would have gone nowhere. Replying to a message you sent now answers its original recipients instead, and says which rule it applied.

update_draft merges rather than replaces. Gmail's API has no partial update, so the underlying call rewrites the whole message; the tool reads the draft first and keeps every field you did not pass, attachments included.

📎 Attachments

Outgoing attachments are local file paths (~ is expanded), assembled into a proper MIME multipart message and sent base64url-encoded via raw.

Gmail's 25 MB ceiling applies to the encoded message, and base64 adds about a third, so the real limit is roughly 18 MB of actual files. Oversized attachments are refused up front, with the per-file arithmetic, rather than being uploaded and rejected by Google with an opaque 400.

save_attachment_to_drive needs the Drive scope. See Scopes.

📤 Sending

Off by default. This server composes; a human sends. A draft can be read, corrected or thrown away; a sent message cannot, because SMTP has no recall.

To enable delivery, set GMAIL_ENABLE_SEND=1 in the server's environment and restart your MCP client:

"env": { "GMAIL_ENABLE_SEND": "1" }

That adds three tools:

📅 Calendar

🔐 Auth

🔑 Scopes

Drive is requested as drive.file, not the full drive scope: it grants rights over the files this app creates and nothing else, so the server cannot read, list or alter anything already in your Drive.

The trade-off is worth knowing. Because the app never gains rights over folders it did not create, passing a folderId for a folder you made in the Drive web UI can come back as "not found" even though it plainly exists. When that happens the file is uploaded to My Drive instead and the result says so, rather than the upload being lost.

Changing this list invalidates existing credentials. Google will not add scopes to a refresh token it has already issued, so a token predating a scope keeps working for everything else while the new feature returns a bare 403. The tools detect that case and tell you to re-run authentication:

npx @spark-apps/gmail-manager-mcp@latest auth

🗄️ Caching

Mail is cached locally so the same message is not downloaded twice, but never at the expense of being current. Gmail hands out a mailbox-wide historyId and a feed of what changed since any earlier value of it, so this server validates its cache against Gmail rather than expiring it on a timer:

• Nothing has changed: the cached answer is provably still exact, and a repeated search costs a single request instead of one per result.
• Something has changed: the list of matching messages is always re-fetched, so new mail, sent mail and anything relabelled show up immediately. Only the per-message headers and bodies are reused, which is safe because Gmail does not let the content of a delivered message change.

There is no staleness window to tune: a message that arrives between two searches appears in the second one.

"env": { "GMAIL_CACHE": "memory" }

Set GMAIL_CACHE=memory on a shared machine if you would rather no mail content touched the disk. The cache is dropped automatically when you authenticate as a different account, and deleting ~/.gmail-mcp/cache/ clears it by hand.

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

📅 Calendar

• "What's on my calendar this week?"
• "Find a 45-minute slot next week when Sam and I are both free, weekdays 9-5"
• "Move Thursday's standup to 10am and add a Meet link"
• "Decline the Friday review, comment that I'm on leave"
• "Search my calendar for anything about the tax deadline"

🛡️ Rules & Unsubscribing

• "Show me the rules currently on my account"
• "Rule: anything from noreply@ skips the inbox and gets labelled Noise"
• "Get the unsubscribe link for this sender so I can check it before clicking"
• "Unsubscribe me from this newsletter"

Unsubscribing uses the sender's own published opt-out. Where they support one-click (RFC 8058) it completes on its own; where the only route is emailing them, it asks first, since that sends mail from your account. A plain link with no one-click declaration is handed back for you to open. Arbitrary URLs found in mail are never visited, and no response body from a sender is ever read back into the conversation.

---

🌱 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
🤝 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 • Terms of Service