Gmail MCP Server

# 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:** ```bash pip install -r requirements.txt ``` 2. **Run the server:** ```bash 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:** ```bash pip install -r requirements.txt ``` 3. **Configure MCP client** using `mcp_config.json`: ```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: ```bash 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.