Gmail-MCP-Server

WHAT IT CONNECTS

Gmail-MCP-Server 为 AI Agent 提供什么

• Send emails with subject, content, attachments, and recipients
• Support for HTML emails and multipart messages with both HTML and plain text versions
• Full support for international characters in subject lines and email content
• Read email messages by ID with advanced MIME structure handling
• View email attachments information (filenames, types, sizes)
• Search emails with various criteria (subject, sender, date range)
• **Comprehensive label management with ability to create, update, delete and list labels**
• List all available Gmail labels (system and user-defined)
• List emails in inbox, sent, or custom labels
• Mark emails as read/unread
• Move emails to different labels/folders
• Delete emails
• **Batch operations for efficiently processing multiple emails at once**
• Full integration with Gmail API
• Simple OAuth2 authentication flow with auto browser launch
• Support for both Desktop and Web application credentials
• Global credential storage for convenience
• Create a Google Cloud Project and obtain credentials:
• Go to [Google Cloud Console](https://console.cloud.google.com/)
• Create a new project or select an existing one
• Enable the Gmail API for your project
• Go to "APIs & Services" > "Credentials"
• Click "Create Credentials" > "OAuth client ID"
• Choose either "Desktop app" or "Web application" as application type
• Give it a name and click "Create"
• For Web application, add `http://localhost:3000/oauth2callback` to the authorized redirect URIs
• Download the JSON file of your client's OAuth keys
• Rename the key file to `gcp-oauth.keys.json`
• Run Authentication:
• Look for `gcp-oauth.keys.json` in the current directory or `~/.gmail-mcp/`
• If found in current directory, copy it to `~/.gmail-mcp/`
• Open your default browser for Google authentication
• Save credentials as `~/.gmail-mcp/credentials.json`
• Configure in Claude Desktop:
• Authentication:
• Usage:
• **Configure Reverse Proxy:**
• Set up your n8n container to expose a port for authentication
• Configure a reverse proxy to forward traffic from your domain (e.g., `gmail.gongrzhe.com`) to this port
• **DNS Configuration:**
• Add an A record in your DNS settings to resolve your domain to your cloud server's IP address
• **Google Cloud Platform Setup:**
• In your Google Cloud Console, add your custom domain callback URL (e.g., `https://gmail.gongrzhe.com/oauth2callback`) to the authorized redirect URIs list
• **Run Authentication:**
• **Configure in your application:**
• Prioritizes plain text content when available
• Falls back to HTML content if plain text is not available
• Handles multi-part MIME messages with nested parts
• Processes attachments information (filename, type, size)
• Preserves original email headers (From, To, Subject, Date)
• Turkish, Chinese, Japanese, Korean, and other non-Latin alphabets
• Special characters and symbols
• Proper encoding ensures correct display in email clients
• **Create Labels**: Create new labels with customizable visibility settings
• **Update Labels**: Rename labels or change their visibility settings
• **Delete Labels**: Remove user-created labels (system labels are protected)
• **Find or Create**: Get a label by name or automatically create it if not found
• **List All Labels**: View all system and user labels with detailed information
• **Label Visibility Options**: Control how labels appear in message and label lists
• `messageListVisibility`: Controls whether the label appears in the message list (`show` or `hide`)
• `labelListVisibility`: Controls how the label appears in the label list (`labelShow`, `labelShowIfUnread`, or `labelHide`)
• Process up to 50 emails at once (configurable batch size)
• Automatic chunking of large email sets to avoid API limits
• Detailed success/failure reporting for each operation
• Graceful error handling with individual retries
• Perfect for bulk inbox management and organization tasks
• OAuth credentials are stored securely in your local environment (`~/.gmail-mcp/`)
• The server uses offline access to maintain persistent authentication
• Never share or commit your credentials to version control
• Regularly review and revoke unused access in your Google Account settings
• Credentials are stored globally but are only accessible by the current user
• **OAuth Keys Not Found**
• Make sure `gcp-oauth.keys.json` is in either your current directory or `~/.gmail-mcp/`
• Check file permissions
• **Invalid Credentials Format**
• Ensure your OAuth keys file contains either `web` or `installed` credentials
• For web applications, verify the redirect URI is correctly configured
• **Port Already in Use**
• If port 3000 is already in use, please free it up before running authentication
• You can find and stop the process using that port
• **Batch Operation Failures**
• If batch operations fail, they automatically retry individual items
• Check the detailed error messages for specific failures
• Consider reducing the batch size if you encounter rate limiting