Gmail MCP Server 📧

A high-performance Model Context Protocol (MCP) server that enables AI assistants to interact with Gmail securely.

MCP Python License

✨ Features

Smart Email Retrieval: Fetch unread messages with rich metadata.
Thread-Aware Drafting: Create replies that maintain conversation context.
Secure Authentication: Robust OAuth 2.0 implementation with token management.
Enterprise Ready: Structured for scalability and maintainability.

🏗️ Architecture

System Data Flow

graph TD
    User(["👤 User"]) <-->|"Natural Language"| Claude(["🤖 Claude Desktop"])
    
    subgraph "MCP Server (Local Machine)"
        Claude <-->|"JSON-RPC (stdio)"| Main["src/main.py"]
        Main -->|Dispatch| Handler["src/handlers.py"]
        Handler -->|Call| Client["src/client.py"]
    end
    
    Client <-->|"HTTPS / OAuth 2.0"| Gmail(["☁️ Google Gmail API"])
    
    style User fill:#f9f,stroke:#333
    style Claude fill:#e1f5fe,stroke:#01579b
    style Gmail fill:#fce4ec,stroke:#880e4f

The project follows standard engineering practices:

MLI/
├── src/
│   ├── main.py          # Application Entry Point
│   ├── client.py        # Gmail API Client
│   └── handlers.py      # Request Handlers
├── config/              # Configuration & Credentials
├── tests/               # Unit Tests
└── requirements.txt     # Dependencies

🚀 Quick Start

1. Prerequisite

Python 3.8+
Google Cloud Project with Gmail API enabled

2. Installation

# Clone and setup environment
python -m venv .venv
.venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

3. Configuration

Place your Google Cloud credentials.json in config/.
Copy the environment config:
```
copy .env.example .env
```

4. Claude Integration

Add to your Claude Desktop config (%APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "gmail": {
      "command": "C:\\Path\\To\\MLI\\.venv\\Scripts\\python.exe",
      "args": ["-m", "src.main"],
      "cwd": "C:\\Path\\To\\MLI",
      "env": {
        "CREDENTIALS_PATH": "config/credentials.json",
        "TOKEN_PATH": "config/token.json"
      }
    }
  }
}

🛠️ Usage

Check Emails:

"Check my unread emails"

Draft Reply:

"Draft a reply to the email from [Name]"

🛡️ Security

Credentials are never committed to version control.
Tokens are stored locally in config/.
Communication happens directly between your machine and Google API.