muammar-yacoob/gmail-manager-mcp

10 stars 5 forks Quality 80 Trend 16MIT

Organize your GMail via MCP

Overview

[//]: # (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 provides to your Gmail inbox through the Model Context Protocol, allowing you to: 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?

README

Gmail Manager MCP

✨ What It Does

Gmail Manager MCP provides direct access to your Gmail inbox through the Model Context Protocol, allowing you to:


	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:
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 🗝️

📥 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.

💻 Terminal Usage

⚙️ Configure MCP Client

🛠️ Available Tools

🔑 Scopes

Scope	Why
`https://mail.google.com/`	Read, label, draft, trash and permanently delete mail
`https://www.googleapis.com/auth/calendar`	Calendar tools
`https://www.googleapis.com/auth/drive.file`	`save_attachment_to_drive`

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.

Variable	Default	Effect
`GMAIL_CACHE`	`full`	`full` keeps the cache in `~/.gmail-mcp/cache/` (owner-only), `memory` keeps it in RAM for the life of the process, `off` disables it
`GMAIL_CACHE_MAX_MESSAGES`	`2000`	Messages held before the least recently used are dropped
`GMAIL_CACHE_MAX_THREADS`	`300`	Conversations held
`GMAIL_CACHE_MAX_QUERIES`	`200`	Search results remembered

"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

🌱 Support & Contributions

⭐ Star the repo & I power up like Mario 🍄
☕ Devs run on coffee - Buy me one?
💰 Crypto tips welcome - Tip in crypto
🤝 Contributions are welcome - 🍴 Fork, improve, PR!
🎥 Need help? Setup Tutorial • Join Discord

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

View the full README on GitHub

Install

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

New to MCP? Start with the mcpskill.org guide →

Configuration

{
  "mcpServers": {
    "gmail-manager": {
      "command": "npx", "args": ["@spark-apps/gmail-manager-mcp@latest"],
      "env": { "GMAIL_OAUTH_PATH": "C:\\path\\to\\gcp-oauth.keys.json" }
    }
  }
}