Skip to main content
Glama
Sign In
benitomartin

Gmail Telegram MCP Server

by benitomartin
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Gmail Telegram MCP Server

Gmail Telegram MCP Server

License: MIT Python version uv

Telegram Google Cloud MCP OpenAI

Table of Contents

Related MCP server: mcp-google-gmail

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:

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

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 git@github.com: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.

Available Tools

2 tools
get_emailsA

Fetch emails from Gmail for a specified number of days. Returns JSON array of emails with id, from, subject, date, and body fields.

NameRequiredDescriptionDefault
daysNo
max_resultsNo

Output Schema

NameRequiredDescription
resultYes

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It discloses the return shape (JSON array with id, from, subject, date, body), which is useful behavioral context, but says nothing about auth requirements, rate limits, or pagination behavior for large mailboxes.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences: purpose first, return contract second. No filler, no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter read tool with an output schema present, the description needn't restate return values, and purpose is fully covered. The remaining gap is the undocumented max_results parameter and absent auth/pagination context, which is minor given the tool's simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and nothing in the schema documents the two parameters. The description only vaguely gestures at 'a specified number of days' for the days parameter and never mentions max_results at all, leaving half the inputs unexplained.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (fetch) and resource (emails from Gmail) plus the scoping dimension (number of days). The only sibling, tts_instagram_audio, is unrelated, so no differentiation is needed and an agent can immediately tell what this does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no guidance on when to use this tool versus alternatives, nor any prerequisites such as Gmail authentication or account scoping. Usage is only implied by the verb 'fetch'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

tts_instagram_audioC

Convert text to speech for Instagram audio messages.

NameRequiredDescriptionDefault
textYes
voice_nameNoen-US-Chirp3-HD-Aoede
language_codeNoen-US

Output Schema

NameRequiredDescription
resultYes

TDQS

C2.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral burden. It does not disclose output audio format/handling, permission or auth needs, rate limits, length caps, or whether it posts/sends to Instagram. The output schema helps with return values, but behavioral traits remain largely undisclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One front-loaded sentence with no filler or wasted words. It is appropriately concise for a simple TTS tool, though its brevity contributes to missing detail elsewhere.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a low-complexity TTS tool with an output schema, the purpose is stated, but with no annotations and 0% schema parameter descriptions, the definition is incomplete. An agent lacks parameter guidance and behavioral context needed to call it optimally.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate and it does not. It mentions no parameter meaning, defaults, voice-name format, or language-code values, leaving voice_name and language_code unexplained.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Convert text to speech') and resource/context ('Instagram audio messages'). The purpose is clear, but it does not differentiate from other possible TTS siblings; the only listed sibling is unrelated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'for Instagram audio messages' implies the intended context, but the description gives no explicit when-to-use guidance, alternatives, prerequisites, or exclusions. Usage is only implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.1.0
    • First observedget_emails
    • First observedtts_instagram_audio
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

C2.8/5.0

Scored across 2 tools

Disambiguation4/5

The two tools have clearly distinct purposes: one fetches emails, the other converts text to speech for Instagram audio. There is no functional overlap, though the Instagram tool feels unrelated to the server's implied Gmail/Telegram scope.

Naming Consistency2/5

Both names use snake_case, but get_emails follows a verb_noun pattern while tts_instagram_audio uses an acronym-plus-domain-plus-noun structure. The conventions are mixed and do not form a predictable pattern.

Tool Count2/5

Two tools are far too few for a server named Gmail Telegram MCP Server, which implies broader Gmail and Telegram operations. The count is not just thin; it leaves major implied functionality uncovered.

Completeness1/5

The surface is severely incomplete for the stated purpose: it only fetches Gmail emails and has no Telegram operations, no email sending, no search, and no clear lifecycle coverage. The Instagram TTS tool does not compensate for these gaps.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • mcp-google-gmail

    MindMadeLab
    A
    license
    Not graded
    quality
    B
    maintenance
    A Python-based MCP server that bridges MCP-compatible clients with the Gmail API, enabling AI-driven email management through natural language commands.
    49 PyPI
    MIT

  • mail-mcp-custom

    cosmingherghe
    A
    license
    Not graded
    quality
    D
    maintenance
    Custom MCP server for Gmail integration, enabling email listing, reading, searching, and sending via natural language.
    ISC