Gmail MCP Server

Gmail MCP Server

A Model Context Protocol (MCP) server that provides comprehensive Gmail functionality through FastMCP. This server enables AI assistants like Claude to interact with Gmail accounts, manage emails, send messages, and perform various Gmail operations using OAuth2 authentication via Nango.

Features

Core Gmail Operations

• Message Management: List, search, read, and delete emails
• Send Emails: Send messages with or without attachments
• Message Actions: Mark messages as read, manage labels
• Advanced Search: Filter by sender, subject, date, attachments, read status
• Account Statistics: Get Gmail account overview and metrics
• Thread Support: Handle Gmail conversation threads
• Attachment Support: Send emails with file attachments

Authentication & Security

• OAuth2 Integration: Secure authentication via Nango
• Token Management: Automatic token refresh and validation
• Multi-account Support: Handle multiple Gmail accounts
• Secure Credential Storage: Environment-based configuration

Prerequisites

• Python 3.13+
• Gmail account with API access enabled
• Google Cloud Project with Gmail API enabled
• Nango account for OAuth2 management (optional but recommended)

Installation

1. Clone or create the project structure:

mkdir gmail-mcp-server
cd gmail-mcp-server

2. Create a virtual environment:

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. Install dependencies:

pip install -e .

Configuration

Environment Variables

Create a .env file in the project root:

# Nango Configuration (Recommended)
NANGO_BASE_URL=https://api.nango.dev
NANGO_SECRET_KEY=your_nango_secret_key
NANGO_CONNECTION_ID=your_NANGO_CONNECTION_ID
NANGO_INTEGRATION_ID=google

# Alternative: Direct Google OAuth (if not using Nango)
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
GOOGLE_REFRESH_TOKEN=your_refresh_token

Google Cloud Setup

1. Create a Google Cloud Project:

   • Go to Google Cloud Console
   • Create a new project or select existing one

2. Enable Gmail API:

   • Navigate to "APIs & Services" > "Library"
   • Search for "Gmail API" and enable it

3. Create OAuth2 Credentials:

   • Go to "APIs & Services" > "Credentials"
   • Click "Create Credentials" > "OAuth 2.0 Client IDs"
   • Choose "Desktop application" or "Web application"
   • Note the Client ID and Client Secret

4. Configure OAuth Scopes:

   • Add the following scopes:
     • https://www.googleapis.com/auth/gmail.readonly
     • https://www.googleapis.com/auth/gmail.send
     • https://www.googleapis.com/auth/gmail.modify

Nango Setup (Recommended)

1. Create Nango Account: Sign up at nango.dev
2. Create Google Integration: Set up Google OAuth2 integration
3. Configure Connection: Create a connection for your Gmail account
4. Get Credentials: Note your connection ID and provider config key

Claude Desktop Configuration

Add this configuration to your Claude Desktop config file:

Location:

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

With Nango

{
  "mcpServers": {
    "gmail": {
      "command": "uvx",
      "args": ["git+https://github.com/ampcome-mcps/gmail-mcp.git"],
      "env": {
        "NANGO_BASE_URL": "https://api.nango.dev",
        "NANGO_SECRET_KEY": "your_nango_secret_key",
        "NANGO_CONNECTION_ID": "your_nango_connection_id",
        "NANGO_INTEGRATION_ID": "google-mail"
      }
    }
  }
}

Notes:

• On Windows, use backslashes in paths: C:\\path\\to\\your\\gmail-mcp-server\\main.py
• For virtual environment on Windows: .venv\\Scripts\\python.exe
• Replace placeholder values with your actual credentials

Available Tools

The MCP server provides the following tools for Claude:

Message Operations

• gmail_list_messages - List Gmail messages with optional search query
• gmail_get_message - Get details of a specific message
• gmail_search_messages - Advanced search with multiple criteria
• gmail_send_message - Send a new email message
• gmail_send_message_with_attachment - Send email with file attachment

Message Management

• gmail_mark_as_read - Mark messages as read
• gmail_delete_messages - Delete messages permanently

Account Information

• gmail_get_stats - Get Gmail account statistics and overview

Usage Examples

Once configured with Claude, you can use natural language commands like:

Basic Operations

• "Show me my latest 10 emails"
• "Search for emails from john@example.com sent this week"
• "Get the full content of message ID xyz123"
• "Send an email to sarah@example.com with subject 'Meeting Tomorrow'"

Advanced Operations

• "Find all unread email