Gmail MCP Server

Gmail MCP Server

A powerful Model Context Protocol (MCP) server that enables Claude AI to directly interact with Gmail.

📖 Table of Contents

• Overview
• Key Features
• Quick Start
  • Prerequisites
  • Installation
  • Set up Google Cloud and OAuth credentials
  • First Run and Authentication
  • Configure Claude Desktop
• Available Tools
• Usage Examples
• Advanced Configuration
  • Environment Variables
  • SSE Server Mode
• Documentation
• Security Considerations
• Contributing
• License
• Acknowledgments

📋 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

1. Clone the repository

   git clone https://github.com/yourusername/gmail-mcp-server.git
   cd gmail-mcp-server
   

2. Set up a virtual environment

   python -m venv venv
   
   # On Windows
   venv\Scripts\activate
   
   # On macOS/Linux
   source venv/bin/activate
   

3. Install dependencies

   pip install -r requirements.txt
   

4. Set 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

Generate an OAuth token for the Gmail account you want to use. Copy the URL printed by the script into a web browser and complete the sign-in process:

python gmail_token_creator.py

Test the server:

python gmail_server.py

Configure Claude Desktop

1. Edit your Claude Desktop configuration file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add the Gmail MCP server to the configuration:

   {
     "mcpServers": {
       "gmail": {
         "command": "/absolute/path/to/gmail-mcp-server/venv/bin/python",
         "args": [
           "/absolute/path/to/gmail-mcp-server/gmail_server.py"
         ]
       }
     }
   }
   

3. 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. Note: No need to run python gmail_server.py by yourself. Claude will run it automatically everytime it starts.

🧰 Available Tools

The Gmail MCP Server exposes the following tools to Claude:

Email Sending

• send_email - Send basic emails with text/HTML content
• send_email_with_attachment - Send emails with file attachments
• send_email_with_multiple_attachments - Send emails with multiple attachments

Email Reading

• read_email - Read the content of a specific email by ID
• get_unread_emails - Get a list of unread emails
• get_important_emails - Get emails marked as important
• get_emails_with_attachments - Get emails that have attachments
• get_recent_emails - Get emails from the last X days

Email Search and Organization

• search_emails - Search emails using Gmail's query syntax
• get_email_labels - List all Gmail labels/folders
• `create_email_lab