muammar-yacoob/GMail-Manager-MCP

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

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

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

# 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

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

📬 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

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

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

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

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

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