Gmail MCP Server v2.0

A comprehensive Model Context Protocol (MCP) server for Gmail with 25+ tools and AI-powered features.

What is This?

This package lets your AI assistant (Cursor, VS Code, etc.) directly interact with your Gmail account. It can search, read, send, organize emails, and even summarize them using AI.

Important: This runs locally on your machine. Your credentials and emails stay private.

🚀 Quick Start

npx @techsend/gmail-mcp-server

But first, you'll need to set up credentials...

📋 Prerequisites

You need two things before using this:

1. Google OAuth Credentials (For Gmail Access)

2. OpenRouter API Key (For AI Features)

Follow the guides below to get both.

🔑 Step-by-Step Setup

Part 1: Get Google OAuth Credentials

This allows the server to access your Gmail account.

1.1 Go to Google Cloud Console

Visit: console.cloud.google.com

1.2 Create a New Project

• Click "Select a project" → "New Project"
• Name it: My Gmail MCP (or anything you like)
• Click "Create"

1.3 Enable Gmail API

• In the search bar, type "Gmail API"
• Click on it → Click "Enable"

1.4 Create OAuth Credentials

1. Go to "Credentials" (left sidebar)
2. Click "Create Credentials" → "OAuth client ID"
3. If prompted, configure the OAuth consent screen:
   • User Type: External
   • App name: My Gmail MCP
   • User support email: Your email
   • Developer email: Your email
   • Click Save and Continue through all steps
4. Back to Create OAuth Client ID:
   • Application type: Desktop app
   • Name: Gmail MCP Desktop
   • Click "Create"

1.5 Download Credentials

• Click the Download button (⬇️) next to your newly created OAuth client
• Save the file as credentials.json

1.6 Place Credentials File

Move credentials.json to this location:

Windows:

C:\Users\YourName\.gmail-mcp\credentials.json

Mac/Linux:

~/.gmail-mcp/credentials.json

Create the .gmail-mcp folder if it doesn't exist.

Part 2: Get OpenRouter API Key

This enables AI summarization features.

2.1 Sign Up

Visit: openrouter.ai

2.2 Get Your Key

1. Click "Sign In" or "Get Started"
2. Log in (or create account)
3. Go to "Keys" section
4. Click "Create Key"
5. Copy your key (starts with sk-or-...)

2.3 Add Credits (Optional)

If you want to use AI summarization, add some credits (starts at $5). The server works without this, but summarize_email won't work.

Part 3: Configure Your IDE

For Cursor

1. Open Cursor settings
2. Find "MCP Servers" section (or edit ~/.cursor/mcp.json)
3. Add this configuration:

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": ["@techsend/gmail-mcp-server"],
      "env": {
        "OPENROUTER_API_KEY": "sk-or-your-actual-key-here"
      }
    }
  }
}

For VS Code (with Roo Code or similar)

Add to .vscode/settings.json:

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": ["@techsend/gmail-mcp-server"],
      "env": {
        "OPENROUTER_API_KEY": "sk-or-your-actual-key-here"
      }
    }
  }
}

Replace sk-or-your-actual-key-here with your real OpenRouter key!

Part 4: First Run & Authentication

1. Restart your IDE (close and reopen)
2. In your AI chat, try: "Find my last 5 emails"
3. A browser window will open
4. Log in with your Google account
5. Grant permissions (Gmail read/write/compose)
6. Close the browser tab
7. ✅ Done! Future requests work automatically

🛠️ Features

📧 Email Operations (15 tools)

| Tool | Example Prompt | |------|----------------| | search_emails | "Find emails from [email protected] this week" | | read_email | "Show me the email from Google" | | send_email | "Send an email to [email protected] saying thanks" | | reply_to_email | "Reply to that email saying I'll be there" | | forward_email | "Forward this to [email protected]" | | trash_email | "Move that email to trash" | | delete_email | "Permanently delete this spam" | | archive_email | "Archive all newsletters" | | mark_as_read | "Mark all emails from today as read" | | star_email | "Star the email from my boss" |

🧵 Thread Operations (2 tools)

• get_thread - "Show me the full conversation"
• list_threads - "List all threads from this week"

🏷️ Label Management (5 tools)

• list_labels - "What labels do I have?"
• create_label - "Create a label called Important"
• add_labels_to_email - "Add the Work label to this email"

📝 Draft Operations (4 tools)

• create_draft - "Create a draft to [email protected] about the meeting"
• list_drafts - "Show me all my drafts"
• send_draft - "Send that draft"

🤖 AI-Powered (1 tool)

• summarize_email - "Summarize that long newsletter"

📊 Utilities (2 tools)

• get_profile - "What's my Gmail address?"
• get_unread_count - "How many unread emails do I have?"

🔒 Privacy & Security

✅ Your data stays local:

• Credentials stored on your machine
• Gmail tokens stored locally
• No data sent to us (the package authors)

✅ OAuth is secure:

• Standard Google authentication
• You can revoke access anytime at myaccount.google.com/permissions

✅ Open source:

• View the code: github.com/techsend/gmail-mcp-server

❓ Troubleshooting

"OAuth keys not found"

• Ensure credentials.json is in ~/.gmail-mcp/credentials.json
• Check the file isn't corrupted (should be valid JSON)

"OPENROUTER_API_KEY not found"

• Check your MCP config env block
• Make sure the key is correct (starts with sk-or-)

"Permission denied" errors

• Delete the token file and re-authenticate:
  • Windows: C:\Users\YourName\.gmail-mcp\token.json
  • Mac/Linux: ~/.gmail-mcp/token.json
• Run the tool again to re-authenticate

"403 Forbidden" from Google

• Your OAuth consent screen needs configuration
• Add yourself as a test user in Google Cloud Console

Tools not appearing in IDE

1. Check MCP config syntax (valid JSON)
2. Restart IDE completely
3. Check IDE's MCP logs for errors

🆘 Support

• Issues: GitHub Issues
• NPM Page: npmjs.com/package/@techsend/gmail-mcp-server

📜 License

MIT - see LICENSE

Made with ❤️ for the MCP community | Star on GitHub ⭐