Gmail MCP Server
A powerful Model Context Protocol (MCP) server that enables Claude AI to directly interact with Gmail.
📖 Table of Contents
- Overview
- Key Features
- Quick Start
- Available Tools
- Usage Examples
- Advanced Configuration
- Documentation
- Security Considerations
- Contributing
- License
- Acknowledgments
📋 Overview
The Gmail MCP Server is a comprehensive implementation that enables AI assistants like Claude to directly interact with Gmail through natural language. It exposes a rich set of tools for email management, enabling seamless integration between conversational AI and your inbox.
💡 Key Features
-
Complete Email Management
- Send plain text and HTML emails with attachments
- Read emails with proper parsing of complex message structures
- Search your inbox with Gmail's powerful query syntax
- Create and update draft emails
- Manage labels, read/unread status, and trash
- Perform batch operations on multiple emails
-
Advanced Integration
- Modern Python codebase with async/await pattern
- Comprehensive error handling and recovery
- Detailed progress reporting
- Secure OAuth authentication flow
- Multiple transport modes (STDIO and SSE)
- Support for different deployment scenarios
🚀 Quick Start
Prerequisites
- Python 3.8 or higher
- A Google Cloud project with the Gmail API enabled
- OAuth 2.0 credentials for the Gmail API
Installation
-
Clone the repository
git clone https://github.com/yourusername/gmail-mcp-server.git cd gmail-mcp-server -
Set up a virtual environment
python -m venv venv # On Windows venv\Scripts\activate # On macOS/Linux source venv/bin/activate -
Install dependencies
pip install -r requirements.txt -
Set up Google Cloud and OAuth credentials
Visit the Google Cloud Console to:
- Create a new project
- Enable the Gmail API
- Set up OAuth consent screen
- Create OAuth Client ID credentials (Desktop application)
- Download credentials as
credentials.jsonin project root
First Run and Authentication
Run the server once to authenticate:
python gmail_server.py
This will open a browser window asking you to authenticate with your Google account. After authentication, a token.json file will be created and saved for future use.
Configure Claude Desktop
-
Edit your Claude Desktop configuration file:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
- macOS:
-
Add the Gmail MCP server to the configuration:
{ "mcpServers": { "gmail": { "command": "python", "args": [ "/absolute/path/to/gmail-mcp-server/gmail_server.py" ] } } } -
Save the file and restart Claude Desktop
Note: Replace "/absolute/path/to/gmail-mcp-server/gmail_server.py" with the actual absolute path to the gmail_server.py file in your cloned repository.
🧰 Available Tools
The Gmail MCP Server exposes the following tools to Claude:
Email Sending
send_email- Send basic emails with text/HTML contentsend_email_with_attachment- Send emails with file attachmentssend_email_with_multiple_attachments- Send emails with multiple attachments
Email Reading
read_email- Read the content of a specific email by IDget_unread_emails- Get a list of unread emailsget_important_emails- Get emails marked as importantget_emails_with_attachments- Get emails that have attachmentsget_recent_emails- Get emails from the last X days
Email Search and Organization
search_emails- Search emails using Gmail's query syntaxget_email_labels- List all Gmail labels/folderscreate_email_label- Create a new labeldelete_email_label- Delete an existing labellabel_email- Apply a label to an emailremove_email_label- Remove a label from an email
Email Status Management
mark_as_read- Mark an email as readmark_as_unread- Mark an email as unreaddelete_email- Move an email to trash
Draft Management
create_email_draft- Create a new draft emailupdate_email_draft- Update an existing draftlist_email_drafts- List available draftssend_draft- Send an existing draft
Batch Operations
batch_apply_label- Apply a label to multiple emailsbatch_delete_emails- Move multiple emails to trash
Account Information
get_email_profile- Get Gmail profile informationsummarize_recent_emails- Create a summary of recent emails
💬 Usage Examples
Here are some example prompts for Claude:
Send an email to john@example.com with the subject "Project Update" and let them know we're still on track for the deadline next week.
Search my inbox for any emails from Bank of America in the last month and summarize them for me.
Find all unread emails from my boss and create a summary of any action items mentioned in them.
Draft an email to the team about the upcoming meeting on Thursday at 2pm. Remind everyone to prepare their weekly updates.
🔧 Advanced Configuration
Environment Variables
The server supports multiple environment variables for customization:
| Variable | Description |
|---|---|
GMAIL_TOKEN_PATH | Custom path to store OAuth token |
GMAIL_CREDENTIALS_PATH | Custom path to OAuth credentials |
GOOGLE_CLIENT_ID | OAuth client ID (alternative to credentials file) |
GOOGLE_CLIENT_SECRET | OAuth client secret (alternative to credentials file) |
MCP_PORT | Port for SSE transport (default: 3000) |
DEBUG | Enable debug mode (true or false) |
SSE Server Mode
The server can be run in SSE (Server-Sent Events) mode for HTTP-based integration:
python gmail_server.py --sse [port]
This starts the server on the specified port (default: 3000), making it accessible via HTTP.
📚 Documentation
- MCP Specification - Learn about the Model Context Protocol
- Gmail API Documentation - Reference for Gmail API capabilities
- Google Cloud OAuth - Details on authentication flows
🔒 Security Considerations
- The server uses OAuth 2.0 for secure Gmail API authentication
- All actions run locally on your machine - emails never pass through third-party servers
- Authentication tokens are stored locally and can be revoked at any time
- The server requires local file access only for reading attachments
- Claude always asks for confirmation before sending or deleting emails
🤝 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 MIT License - see the LICENSE file for details.
🙏 Acknowledgments
- Google for the Gmail API
- Anthropic for Claude and the Model Context Protocol
- Contributors to the Python Gmail API client libraries