📌Overview

Purpose: This framework serves to integrate Gmail functionalities into MCP clients, enabling users to access and manage their emails seamlessly.

Overview: The Gmail MCP Server is a Model Context Protocol (MCP) server that connects to Gmail, allowing MCP clients like Claude Desktop to interact with users' email accounts. Users can view recent emails, perform searches using Gmail's syntax, and authenticate securely through OAuth2.

Key Features:

• Email Access: Users can view their ten most recent emails directly from their Gmail inbox, providing a quick and efficient way to stay updated.

• Search Functionality: The server supports extensive email searching capabilities utilizing Gmail's search syntax, enabling users to find specific emails easily.

• Secure Authentication: The framework employs OAuth2 for secure authentication with Gmail, ensuring users' data remains safe while granting read-only access to their emails.

---

Gmail MCP Server

An MCP (Model Context Protocol) server providing Gmail integration capabilities for MCP clients like Claude Desktop.

Features

• View recent emails from your Gmail inbox
• Search emails using Gmail's search syntax
• Secure OAuth2 authentication with the Gmail API

Setup

Google Cloud Project Setup

1. Create a Google Cloud Project at https://console.cloud.google.com/.
2. Enable the Gmail API.
3. Create OAuth 2.0 credentials (Application type: Desktop application) and download credentials.json.

Installation

# Create a conda environment
conda create -n mcp-gmail python=3.12
conda activate mcp-gmail

# Install the package
cd gmail-mcp-server
pip install -e .

Configuration for Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "gmail": {
      "command": "/path/to/conda/envs/mcp-gmail/bin/python",
      "args": ["-m", "gmail_mcp_server.server"],
      "env": {
        "PYTHONPATH": "/path/to/gmail-mcp-server/src",
        "GMAIL_CREDENTIALS_FILE": "/path/to/credentials.json",
        "GMAIL_TOKEN_FILE": "/path/to/token.json"
      }
    }
  }
}

Replace /path/to/ with your actual paths. The token file will be created automatically when you first authenticate.

First Run

On first access to Gmail through Claude, you will be prompted to authorize the application in your browser. Your credentials will be saved to the token file for future use.

Available Resources

• gmail://inbox/recent - Returns your 10 most recent emails.

Available Tools

• search_emails
  • Description: Search Gmail emails with a query.
  • Parameters:
    • query (required): Gmail search query.
    • max_results (optional): Maximum number of results to return (default: 10).

Example search query:

Could you show me any emails from sanrio in the last two days?

Security

• OAuth2 authentication with Gmail is required.
• Credentials are stored locally in the token file.
• Access can be revoked at any time through your Google Account settings.
• Only read access to Gmail is requested (no write permissions).

Environment Variables

• GMAIL_CREDENTIALS_FILE (required): Path to your Google OAuth credentials file.
• GMAIL_TOKEN_FILE (required): Path where the authentication token will be saved.

For testing, you can run the server directly:

GMAIL_CREDENTIALS_FILE="/path/to/credentials.json" \
GMAIL_TOKEN_FILE="/path/to/token.json" \
python -m gmail_mcp_server.server

Development

The server uses the Model Context Protocol to provide:

• Resource access to recent emails.
• Tool support for email searches.
• Secure OAuth2 authentication flow with automatic token refresh.

Logging

The server logs detailed information about its operations, including:

• Server startup information
• Authentication status
• Resource and tool usage
• Any errors or issues

Contributing

Pull requests are welcome! Please ensure to:

• Update documentation for new features
• Add appropriate error handling
• Test the OAuth flow with new features
• Follow existing code style