email-mcp

This repository implements a Model Context Protocol (MCP) service integrated with the Gmail API, enabling language models to interact with email data. It includes tools like list_emails, list_emails_by_domain, and send_reply, and is structured for easy extension.

Features

• Retrieve recent emails from Gmail
• Filter emails by domain (e.g., @gmail.com)
• Reply to emails using predefined message templates
• Integrate with MCP-compatible language model systems

Tech Stack

• Python 3.9+
• Gmail API (OAuth2)
• MCP Protocol
• Dependency management via uv

Prerequisites

• Install Python >=3.9
• Install uv
• Enable Gmail API in Google Cloud and download credentials.json
• On first run, token.json will be created via browser-based OAuth

Installation

git clone https://github.com/Jarm1ng/email-mcp.git
cd email-mcp
uv venv
uv pip install -r requirements.txt

Credential Setup

Place your credentials.json in the credentials/ directory.

First-time authentication will generate token.json.

MCP Configuration Example

Create a .mcp/mcp.json file with:

{
  "mcpServers": {
    "email-mcp": {
      "command": "python",
      "args": ["main.py"],
      "env": {
        "PATH": "/usr/local/bin:/usr/bin:/bin",
        "PYTHONPATH": "/absolute/path/to/email-mcp",
        "GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/to/email-mcp/credentials/credentials.json"
      },
      "timeout": 60000
    }
  }
}

Replace /absolute/path/to/email-mcp with your actual path.

Usage

To run the tool server:

python main.py

To test with a client script:

python test_client.py

Project Structure

email-mcp/
├── main.py
├── test_client.py
├── test_gmail.py
├── credentials/
├── pyproject.toml
├── uv.lock
└── .vscode/

License

MIT License. See LICENSE file.

Issues

For bug reports or suggestions, please open an issue at
https://github.com/Jarm1ng/email-mcp/issues