Gmail MCP Server v2.0

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

Quick Start

npx @yourusername/gmail-mcp-server

Installation

Prerequisites

• Node.js 18+ installed
• Google Cloud OAuth credentials
• OpenRouter API key (for AI features)

Step 1: Get Google OAuth Credentials

1. Go to Google Cloud Console
2. Create a new project or select existing
3. Enable Gmail API
4. Go to Credentials → Create Credentials → OAuth Client ID
5. Choose Desktop app
6. Download the JSON file
7. Rename it to credentials.json

Step 2: Get OpenRouter API Key

1. Visit OpenRouter
2. Sign up and get your API key
3. Copy the key (starts with sk-or-...)

Step 3: Configure Your IDE

Add this to your MCP settings (.vscode/settings.json or ~/.cursor/mcp.json):

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

Step 4: Add Credentials

Place your credentials.json in your home directory:

• Windows: C:\Users\YourName\.gmail-mcp\credentials.json
• Mac/Linux: ~/.gmail-mcp/credentials.json

Step 5: First Run

When you first use a Gmail tool in your IDE, a browser window will open:

1. Log in with your Google account
2. Grant the requested permissions
3. Close the tab

You're all set! 🎉

Features

📧 Email Operations (15 tools)

• search_emails - Search with Gmail syntax
• read_email - Read full content
• send_email - Send new emails (CC/BCC support)
• reply_to_email - Reply to emails
• forward_email - Forward emails
• trash_email / untrash_email - Trash management
• delete_email - Permanent deletion
• archive_email - Archive emails
• mark_as_read / mark_as_unread - Read status
• star_email / unstar_email - Star management

🧵 Thread Operations (2 tools)

• get_thread - Get full conversation
• list_threads - List matching threads

🏷️ Label Management (5 tools)

• list_labels - Get all labels
• create_label / delete_label - Manage labels
• add_labels_to_email / remove_labels_from_email - Apply labels

📝 Draft Operations (4 tools)

• list_drafts - List all drafts
• create_draft - Create new draft
• delete_draft - Delete draft
• send_draft - Send draft

🤖 AI-Powered (1 tool)

• summarize_email - Summarize with Gemini 2.5

📊 Utilities (2 tools)

• get_profile - User profile
• get_unread_count - Count unread

Usage Examples

In Your IDE

Just ask naturally:

• "Find emails from john@example.com this week"
• "Reply to the last email saying I'll be there"
• "Star all unread emails from my boss"
• "Create a draft thanking Alice for the meeting"
• "Summarize that long newsletter email"

Required OAuth Scopes

The server requests these Gmail permissions:

• gmail.readonly - Read emails
• gmail.modify - Modify emails (labels, read status)
• gmail.compose - Send emails and drafts
• gmail.labels - Manage labels

Configuration Options

Environment Variables

You can also use a .env file in your project:

OPENROUTER_API_KEY=sk-or-your-key-here

Custom Credentials Path

Set the path to your credentials:

{
  "env": {
    "GMAIL_CREDENTIALS_PATH": "/path/to/credentials.json"
  }
}

Troubleshooting

"OAuth keys not found"

• Ensure credentials.json is in ~/.gmail-mcp/ or set GMAIL_CREDENTIALS_PATH

"OPENROUTER_API_KEY not found"

• Add the key to your MCP config's env block

"Permission denied"

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

Development

Clone and build locally:

git clone https://github.com/yourusername/gmail-mcp-server
cd gmail-mcp-server
npm install
npm run build
npm link

Contributing

Contributions welcome! Please open an issue or PR.

License

MIT - see LICENSE file

Support

• Issues: GitHub Issues
• Docs: Full Documentation

Made with ❤️ for the MCP community