Provides tools for managing Gmail emails including reading, sending, searching, and marking messages as read/unread through OAuth2 authentication with the Gmail API
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.txtRun the server:
python gmail_mcp_server.pyFirst time setup:
Use the
authenticate_gmail
tool to authorize accessThis will open your browser for Google OAuth consent
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.example
togcp-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.txtConfigure 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:
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.pickle
file secure
License
This project is provided as-is for educational and integration purposes.
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.
Enables interaction with Gmail through the Gmail API with OAuth2 authentication. Supports reading, sending, searching emails, and managing read status through natural language.