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

1. Install dependencies:

   pip install -r requirements.txt
   

2. Run the server:

   python gmail_mcp_server.py
   

3. First time setup:

   • Use the authenticate_gmail tool to authorize access
   • This 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 address
• subject (required): Email subject
• body (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 query
• max_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 emails
• from:example@gmail.com - Emails from specific sender
• subject:important - Emails with "important" in subject
• has:attachment - Emails with attachments
• after:2024/01/01 - Emails after specific date

Configuration

• Credentials file: gcp-oauth.keys.json (your GCP OAuth credentials - see gcp-oauth.keys.json.example)
• Token file: token.pickle (created automatically after authentication)
• MCP config: mcp_config.json (for MCP client configuration)

Setup Credentials

1. Copy gcp-oauth.keys.json.example to gcp-oauth.keys.json
2. Replace the placeholder values with your actual GCP OAuth credentials
3. Ensure Gmail API is enabled in your Google Cloud project

Integration

To integrate this server with other projects:

1. Copy the core files:

   • gmail_mcp_server.py - Main server
   • requirements.txt - Dependencies
   • gcp-oauth.keys.json - Your OAuth credentials

2. Install dependencies:

   pip install -r requirements.txt
   

3. 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.pickle file secure

License

This project is provided as-is for educational and integration purposes.