Enables comprehensive email management including sending emails with attachments, reading and searching messages, managing labels and drafts, performing batch operations, and handling email status (read/unread, trash, important)
Utilizes Google Cloud Console for project setup, API enablement, OAuth consent screen configuration, and credential management to authenticate with Gmail services
Gmail MCP Server
A powerful Model Context Protocol (MCP) server that enables Claude AI to directly interact with Gmail.
๐ Table of Contents
๐ 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-serverSet up a virtual environment
python -m venv venv # On Windows venv\Scripts\activate # On macOS/Linux source venv/bin/activateInstall dependencies
pip install -r requirements.txtSet 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.json
in project root
First Run and Authentication
Run the server once to authenticate:
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
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:
๐ง Advanced Configuration
Environment Variables
The server supports multiple environment variables for customization:
Variable | Description |
| Custom path to store OAuth token |
| Custom path to OAuth credentials |
| OAuth client ID (alternative to credentials file) |
| OAuth client secret (alternative to credentials file) |
| Port for SSE transport (default: 3000) |
| Enable debug mode (
or
) |
SSE Server Mode
The server can be run in SSE (Server-Sent Events) mode for HTTP-based integration:
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
This server cannot be installed
local-only server
The server can only run on the client's local machine because it depends on local resources.
Enables Claude AI to directly interact with Gmail through natural language for comprehensive email management including sending, reading, searching, organizing, and managing drafts and labels. Uses secure OAuth authentication and runs locally without third-party servers.