Gmail Auto-Auth MCP Server
by GongRzhe
Full Gmail integration with automatic OAuth authentication for AI assistants
communication Node.js Intermediate Self-hostable Docker
⭐ 1.0k stars 📦 34.9k/week 📅 Updated: 8mo ago
Description
An MCP server for Gmail that stands out for its automatic OAuth2 authentication flow — it launches the browser, handles the callback, and stores credentials globally so setup is done once. Provides 19 tools covering email operations (send, draft, read, search, delete), full attachment support (send, receive, download), comprehensive label management (CRUD), batch operations for up to 50 emails at a time, and advanced filter creation with pre-defined templates. Supports HTML and multipart emails with international character encoding. With 34,000+ weekly npm downloads, it's one of the most widely used Gmail MCP servers.
✅ Best for
Developers who want hassle-free Gmail integration with AI assistants and need full email management capabilities
⏭️ Skip if
You need multi-provider email support or prefer a server-side OAuth flow without browser interaction
💡 Use cases
- Sending and drafting emails with attachments through AI assistants
- Searching and organizing inbox using Gmail's advanced search syntax
- Automating email labeling and filtering with template-based rules
- Batch-processing emails for classification or cleanup
- Reading and downloading email attachments for data extraction
👍 Pros
- ✓ Automatic OAuth2 authentication — no manual token setup needed
- ✓ 34,000+ weekly npm downloads, well-tested in production
- ✓ Full attachment support for sending, receiving, and downloading
- ✓ Batch operations handle up to 50 emails at once
- ✓ Filter templates for common scenarios like auto-labeling
👎 Cons
- ✗ Requires Google Cloud OAuth credentials setup (one-time)
- ✗ Limited to Gmail — does not support other email providers
- ✗ 71 open issues suggest some edge cases remain unresolved
🔧 Exposed tools (15 tools)
| Tool | Category | Description |
|---|---|---|
| batch_modify_emails | batch-operations | Modify labels for multiple emails efficiently in batches of up to 50 |
| batch_delete_emails | batch-operations | Permanently delete multiple emails in batches |
| send_email | email-operations | Send new emails with subject, content, optional attachments, and recipients |
| draft_email | email-operations | Create draft emails without sending, with attachment support |
| read_email | email-operations | Retrieve specific email content by ID with attachment information |
| download_attachment | email-operations | Download email attachments to local filesystem |
| search_emails | email-operations | Search emails using Gmail search syntax and criteria |
| modify_email | email-operations | Add or remove labels from emails |
| delete_email | email-operations | Permanently delete an email |
| create_filter | filter-management | Create Gmail filters with custom criteria and actions |
| list_filters | filter-management | Retrieve all Gmail filters |
| create_filter_from_template | filter-management | Create filters using pre-defined templates for common scenarios |
| list_email_labels | label-management | Retrieve all available Gmail labels |
| create_label | label-management | Create new Gmail labels |
| get_or_create_label | label-management | Get existing label or create if not found |
💡 Tips & tricks
Run 'npx @gongrzhe/server-gmail-autoauth-mcp auth' once to complete the OAuth flow. Credentials are stored globally at ~/.gmail-mcp/credentials.json so they work from any project directory. Use create_filter_from_template for quick inbox rules.
Quick info
- Author
- GongRzhe
- License
- MIT
- Runtime
- Node.js 18+
- Transport
- stdio
- Category
- communication
- Difficulty
- Intermediate
- Self-hostable
- ✅
- Auth
- —
- Docker
- 🐳 Docker available
- Version
- 1.1.11
- Updated
- Aug 6, 2025
Client compatibility
- ❓ Claude Code
- ❓ Cursor
- ❓ VS Code Copilot
- ❓ Gemini CLI
- ❓ Windsurf
- ❓ Cline
- ❓ JetBrains AI
- ❓ Warp
Platforms
🍎 macOS 🐧 Linux 🪟 Windows