Gmail Auto-auth

A Model Context Protocol server for Gmail integration with automatic OAuth authentication support. Enables AI assistants to manage Gmail through natural language interactions.

Features

• Send & Draft Emails: Send emails immediately or create drafts with full HTML/plain text support
• Full Attachment Support: Send and receive file attachments, download attachments to local filesystem
• Advanced Email Reading: Read messages with enhanced MIME structure handling and attachment display (filename, type, size, download ID)
• Search & Filter: Powerful Gmail search syntax support, create and manage filters with templates
• Label Management: Create, update, delete, and list labels with customizable visibility settings
• Batch Operations: Efficiently process multiple emails at once (up to 50 per batch)
• Email Organization: Mark as read/unread, move between labels, archive, delete
• International Support: Full support for international characters in subjects and content
• Auto Authentication: Simple OAuth2 flow with automatic browser launch and global credential storage

Authentication Setup

1. Create a Google Cloud Project at Google Cloud Console
2. Enable the Gmail API for your project
3. Create OAuth 2.0 Credentials (Desktop app or Web application)
4. Download credentials as gcp-oauth.keys.json
5. Run authentication: npx @gongrzhe/server-gmail-autoauth-mcp auth
6. Credentials are stored globally in ~/.gmail-mcp/

For web application credentials, add http://localhost:3000/oauth2callback to authorized redirect URIs.

Filter Management

Create filters with various criteria:

• from, to, subject - Filter by sender, recipient, or subject
• hasAttachment - Emails with attachments
• size and sizeComparison - Filter by email size
• query - Gmail search query syntax

Apply actions:

• Add/remove labels
• Forward to another address
• Archive, mark as read/unread

Filter Templates

Pre-built templates for common scenarios:

• fromSender - Filter emails from specific senders
• withSubject - Filter by subject text
• withAttachments - All emails with attachments
• largeEmails - Emails larger than specified size
• containingText - Filter by content
• mailingList - Organize mailing list emails

Tools

• send_email - Send emails with attachments, HTML, and multipart support
• draft_email - Create email drafts with attachments
• read_email - Read email content with enhanced attachment information
• download_attachment - Download email attachments to local filesystem
• search_emails - Search using Gmail query syntax
• modify_email - Add/remove labels from emails
• delete_email - Permanently delete emails
• list_email_labels - List all Gmail labels
• create_label, update_label, delete_label - Label management
• get_or_create_label - Find or create labels
• batch_modify_emails, batch_delete_emails - Batch operations
• create_filter, list_filters, get_filter, delete_filter - Filter management
• create_filter_from_template - Create filters from templates