Gmail MCP Server
A Model Context Protocol (MCP) server that provides tools for interacting with Gmail through the Gmail API.
Features
- 🔐 OAuth2 Authentication - Secure authentication with Google's OAuth2
- 📧 Read Emails - List and read emails from your Gmail inbox
- ✉️ Send Emails - Send emails through Gmail
- 🔍 Search Emails - Search emails using Gmail's powerful search syntax
- 📌 Mark as Read/Unread - Manage email read status
- 🛡️ Secure - Uses Google's official authentication flow
Quick Start
-
Install dependencies:
pip install -r requirements.txt -
Run the server:
python gmail_mcp_server.py -
First time setup:
- Use the
authenticate_gmailtool to authorize access - This will open your browser for Google OAuth consent
- Use the
Available Tools
authenticate_gmail
Authenticate with Gmail API using OAuth2. Must be run first.
list_emails
List emails from your Gmail inbox.
max_results(optional): Maximum number of emails to return (default: 10)query(optional): Gmail search query
read_email
Read a specific email by its ID.
email_id(required): The ID of the email to read
send_email
Send an email through Gmail.
to(required): Recipient email addresssubject(required): Email subjectbody(required): Email body (plain text)cc(optional): CC email addresses (comma-separated)bcc(optional): BCC email addresses (comma-separated)
search_emails
Search emails using Gmail search syntax.
query(required): Gmail search querymax_results(optional): Maximum number of results (default: 10)
mark_as_read / mark_as_unread
Mark an email as read or unread.
email_id(required): The ID of the email to modify
Gmail Search Syntax
is:unread- Unread emailsfrom:example@gmail.com- Emails from specific sendersubject:important- Emails with "important" in subjecthas:attachment- Emails with attachmentsafter:2024/01/01- Emails after specific date
Configuration
- Credentials file:
gcp-oauth.keys.json(your GCP OAuth credentials - seegcp-oauth.keys.json.example) - Token file:
token.pickle(created automatically after authentication) - MCP config:
mcp_config.json(for MCP client configuration)
Setup Credentials
- Copy
gcp-oauth.keys.json.exampletogcp-oauth.keys.json - Replace the placeholder values with your actual GCP OAuth credentials
- Ensure Gmail API is enabled in your Google Cloud project
Integration
To integrate this server with other projects:
-
Copy the core files:
gmail_mcp_server.py- Main serverrequirements.txt- Dependenciesgcp-oauth.keys.json- Your OAuth credentials
-
Install dependencies:
pip install -r requirements.txt -
Configure MCP client using
mcp_config.json:{ "mcpServers": { "gmail": { "command": "python", "args": ["gmail_mcp_server.py"], "cwd": "/path/to/your/gmail/mcp/server" } } }
Testing
Run the included test to verify functionality:
python direct_test.py
This will test authentication, email listing, searching, and sending.
Security
- OAuth2 credentials are stored securely using Google's official libraries
- Access tokens are refreshed automatically
- All API calls use HTTPS
- Keep
token.picklefile secure
License
This project is provided as-is for educational and integration purposes.