Table of Contents

• Gmail Telegram MCP Server
  • Table of Contents
  • Overview
  • Project Structure
  • Prerequisites
• Environment Variables
  • Installation
  • Usage
    • Configuration
    • Google Cloud Project Setup
    • Modules
    • Run the Telegram bot
    • Testing
    • Quality Checks
  • License

Overview

Gmail Telegram MCP Server is a Python project that connects Gmail and Telegram using a Model Context Protocol (MCP) server.

It allows to interact with Gmail emails via a Telegram bot. The following commands are available:

• /start - Start interaction with the bot
• /summary_today - Quick text summary of today's emails
• /audio_today - Quick audio summary of today's emails
• /summary - Smart agent; decides timeframe & format (text/audio/both)

You can read the article about this project in my Substack Newsletter:

• Article

Project Structure

├── Makefile
├── pyproject.toml
├── pre-commit-config.yaml
├── README.md
├── run_bot.py
├── uv.lock
├── src/
│   └── voice_agent/
│       ├── config.py                    # Configuration settings
│       ├── client/                      # Client-side code
│       │   └── agent.py                 # Voice agent client
│       ├── host/
│       │   └── bot.py                   # Telegram bot
│       ├── server/
│       │   ├── gmail_server.py          # Gmail server logic
│       │   ├── prompts/
│       │   │   ├── email_prompts.py     # Email-related prompts
│       │   │   └── prompt_calls.py      # Prompt call definitions
│       │   └── tools/
│       │       ├── get_emails.py        # Email retrieval tool
│       │       └── tts_reply.py         # Text-to-speech tool
│       └── utils/
│           ├── email_parser_util.py     # Email parsing utilities
│           ├── gmail_auth_util.py       # Gmail authentication utilities
│           ├── logger_util.py           # Logging utilities
│           └── openai_utils.py          # OpenAI API utilities
├── test/                                # Unit/Integration tests

Prerequisites

• Python 3.12
• uv (for environment and package management)
• Google Cloud Project
• Telegram Bot with a bot token
• OpenAI API key

Environment Variables

Create a .env file in the root directory with the following variables:

TELEGRAM__BOT_TOKEN=your_bot_token
OPENAI__API_KEY=your_openai_api
OPENAI__MODEL=gpt-4o-mini
GOOGLE__CLIENT_ID=your_client_id
GOOGLE__CLIENT_SECRET=your_client_secret
GOOGLE__APPLICATION_CREDENTIALS=path_to_your_credentials.json
GOOGLE__SCOPES='["https://www.googleapis.com/auth/gmail.readonly"]'
GOOGLE__REDIRECT_URIS='["http://localhost"]'
GOOGLE__AUTH_URI=https://accounts.google.com/o/oauth2/auth
GOOGLE__TOKEN_URI=https://oauth2.googleapis.com/token

Additionally, after the first authentication, this token will be generated and added automatically to the .env file to make the session persistent:

GOOGLE__GMAIL_TOKEN=your_gmail_token

Installation

1. Clone the repository:

   git clone [email protected]:benitomartin/gmail-telegram-mcp-server.git
   cd gmail-telegram-mcp-server

1. Create a virtual environment:

   uv venv
   

2. Activate the virtual environment:

   source .venv/bin/activate
   

3. Install the required packages:

   uv sync --all-groups
   

4. Create a .env file in the root directory:

   cp env.example .env
   

Usage

Configuration

Configure API keys, model names, and other settings in:

• src/voice_agent/config.py
• .env file

Google Cloud Project Setup

1. Create a Google Cloud Project.

2. Enable the Gmail API and Cloud Text-to-Speech API for your project.

3. Under "APIs & Services" > "OAuth consent screen", create your app (external) and configure the necessary scopes.

   1. Add the following scopes (also in the .env file):
      • https://www.googleapis.com/auth/gmail.readonly

4. Add your email address as an authorized tests user.

5. Create OAuth 2.0 credentials (application type: Desktop App) and copy the client ID and secret to your .env file.

6. Run the following command to set the GOOGLE__APPLICATION_CREDENTIALS variable. Add the path of the credentials JSON file to the .env file. In Linux/Ubuntu is under /home/user/.config/gcloud/application_default_credentials.json

   gcloud auth application-default login
   

Modules

• Voice Agent: Handles voice interactions and agent logic.
• Client: Contains the agent for client-side operations.
• Host: Telegram bot integration.
• Server: Gmail server logic, prompt management, and tools for email and TTS.
• Utils: Utilities for email parsing, Gmail authentication, logging, and OpenAI integration.

Run the Telegram bot

uv run run_bot.py

Testing

Run all tests:

make tests

Quality Checks

Run all quality checks (lint, format, type check, clean):

make all

Individual Commands:

• Display all available commands:

  make help
  

• Check code formatting and linting:

  make all-check
  

• Fix code formatting and linting:

  make all-fix
  

• Clean cache and build files:

  make clean
  

License

This project is licensed under the MIT License - see the LICENSE file for details.