Enables comprehensive email management through Gmail, including sending/reading emails, managing drafts, organizing with labels and folders, searching and filtering emails, and archiving functionality.
Leverages Google Cloud project with Gmail API for authentication and API access to provide email management capabilities.
Enhanced Gmail MCP Server
A powerful and feature-rich Model Context Protocol (MCP) server for Gmail integration, written in Python. This server enables AI assistants like Claude to interact with Gmail through natural language, providing comprehensive email management capabilities.
🌟 Key Features
📧 Complete Email Management
Send emails with customizable subject, content, and recipients
Read and retrieve email content with full metadata
Move emails to trash with confirmation
Mark emails as read/unread
Open emails directly in browser
📝 Draft Management
Create draft emails for later review
List all draft emails
Edit existing drafts
🏷️ Advanced Label Management
List all available labels
Create custom labels
Apply/remove labels from emails
Rename existing labels
Delete unused labels
Search emails by label
📁 Folder Organization
Create new folders (implemented as Gmail labels)
Move emails between folders
List all available folders
🔍 Powerful Search & Filtering
Search emails using Gmail's advanced query syntax
Create, manage, and delete email filters
Filter by sender, recipient, subject, content, and more
Customize search results with flexible parameters
🗄️ Archive Management
Archive emails (remove from inbox without deleting)
Batch archive multiple emails matching search criteria
List all archived emails
Restore archived emails to inbox
🚀 Getting Started
Prerequisites
Python 3.8+
Google Cloud project with Gmail API enabled
OAuth 2.0 credentials
Installation
Google Cloud Setup
Create a new Google Cloud project
Configure the OAuth consent screen:
Select "External" user type
Add your email as a test user
Add the scope:
https://www.googleapis.com/auth/gmail/modify
Create OAuth 2.0 credentials:
Choose "Desktop app" as the application type
Download the JSON credentials file
Configuration
Store your credentials securely and specify their location when running the server:
🔧 Usage
Running with Claude Desktop
Add the following to your Claude Desktop configuration file (typically at ~/Library/Application Support/Claude/claude_desktop_config.json
):
Testing with MCP Inspector
For testing and debugging, use the MCP Inspector:
🔐 Security Considerations
Never commit credentials or token files to version control
Store credentials in a secure location with appropriate permissions
The server will request user confirmation before performing sensitive actions
Review Google Cloud Console regularly for unusual activity
Consider using environment variables for sensitive paths
🛠️ Architecture
This implementation features a comprehensive single-file architecture that handles all Gmail operations through the Google API client libraries. Key components include:
OAuth2 authentication with automatic token refresh
Comprehensive error handling and logging
Structured tool definitions with clear input schemas
Efficient email parsing and formatting
📚 Example Prompts
Try these prompts with Claude after connecting the Gmail MCP server:
"Show me my unread emails"
"Search for emails from example@domain.com with attachments"
"Create a new label called 'Important Projects'"
"Draft an email to john@example.com about the upcoming meeting"
"Archive all emails from newsletter@example.com"
"Create a filter to automatically label emails from my team"
🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Fork the repository
Create your feature branch (
git checkout -b feature/amazing-feature
)Commit your changes (
git commit -m 'Add some amazing feature'
)Push to the branch (
git push origin feature/amazing-feature
)Open a Pull Request
📄 License
This project is licensed under the GPL-3.0 License - see the LICENSE file for details.
🙏 Acknowledgments
Inspired by various MCP server implementations in the community
Built with the Model Context Protocol framework
Uses Google's official API client libraries
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
A Model Context Protocol server that enables AI assistants like Claude to interact with Gmail through natural language, providing comprehensive email management capabilities including sending, reading, organizing, searching, and managing drafts and labels.
Related MCP Servers
- -securityFlicense-qualityA Model Context Protocol server that enables AI assistants to interact with Gmail services, supporting email operations, draft management, and calendar functionality through Google API integration.Last updated -431
- AsecurityAlicenseAqualityA Model Context Protocol server that enables AI assistants like Claude to interact with Google Cloud Platform environments through natural language, allowing users to query and manage GCP resources during conversations.Last updated -9246166MIT License
- -securityAlicense-qualityA Model Context Protocol server that enables AI assistants to manage Gmail through natural language interactions with features like sending emails, searching, and label management.Last updated -2,697MIT License
- -securityAlicense-qualityA Model Context Protocol server that enables Claude AI to interact with Gmail, supporting email sending, reading, searching, labeling, draft management, and batch operations through natural language commands.Last updated -MIT License