gmail-telegram

Gmail Telegram MCP Server

Installation

Run this command in your terminal to add the MCP server to Claude Code.

Run in terminal:

Command

claude mcp add --transport stdio benitomartin-gmail-telegram-mcp-server uvx run run_bot.py \
  --env OPENAI__MODEL="gpt-4o-mini" \
  --env GOOGLE__SCOPES="'["https://www.googleapis.com/auth/gmail.readonly"]'" \
  --env OPENAI__API_KEY="your_openai_api_key" \
  --env GOOGLE__AUTH_URI="https://accounts.google.com/o/oauth2/auth" \
  --env GOOGLE__CLIENT_ID="your_client_id" \
  --env GOOGLE__TOKEN_URI="https://oauth2.googleapis.com/token" \
  --env GOOGLE__GMAIL_TOKEN="your_gmail_token (generated after first auth)" \
  --env TELEGRAM__BOT_TOKEN="your_bot_token" \
  --env GOOGLE__CLIENT_SECRET="your_client_secret" \
  --env GOOGLE__REDIRECT_URIS="'["http://localhost"]'" \
  --env GOOGLE__APPLICATION_CREDENTIALS="path_to_your_credentials.json"

How to use

This MCP server connects Gmail to Telegram by running a Python-based MCP server that exposes a Telegram bot interface. The bot lets you interact with your Gmail inbox via chat, offering commands to summarize today's emails and to generate smart summaries across timeframes. The server is organized into a Voice Agent, Client, Host (Telegram bot), Server (Gmail logic, prompts, and tools), and Utils for parsing, Gmail auth, logging, and OpenAI integration. To use it, configure the environment variables with your Telegram bot token, Google OAuth credentials, and OpenAI API key. Then start the bot using the MCP runner (uv) so the Telegram bot can receive user messages and fetch Gmail data as needed. The main user-facing capabilities are: /start to begin, /summary_today for a quick text summary of today's messages, /audio_today for an audio summarization, and /summary which uses a smart agent to decide timeframe and format (text, audio, or both).

How to install

Prerequisites:

Python 3.12+ installed
uv (for environment and package management)
Google Cloud project with Gmail API enabled
Telegram bot token
OpenAI API key

Install steps:

Clone the repository

git clone git@github.com:benitomartin/gmail-telegram-mcp-server.git
cd gmail-telegram-mcp-server

Create and activate a Python virtual environment (via uv):

uv venv
source .venv/bin/activate

Install dependencies and sync groups via uv:

uv sync --all-groups

Create a .env file from the example:

cp env.example .env

Start the MCP server (via uv runner in this project):

uv run run_bot.py

Ensure your Google application credentials are placed as described in the .env file and that all required environment variables are populated.

Additional notes

Environment variables are critical for authentication and API access. Ensure GOOGLE__APPLICATION_CREDENTIALS points to your Google credentials JSON and that GOOGLE__SCOPES includes Gmail read access. After first Gmail authentication, GOOGLE__GMAIL_TOKEN will be created and appended to the .env file for session persistence. If the bot stops unexpectedly, verify network access to Google and Telegram, and check logs under the src/utils and server directories. For updates or upgrades, re-run: uv sync --all-groups. If you plan to run this in Docker or a different runtime, adapt the mcp_config accordingly.

Related MCP Servers

NagaAgent

1.4k

A simple yet powerful agent framework for personal assistants, designed to enable intelligent interaction, multi-agent collaboration, and seamless tool integration.

MCP-Bridge

916

A middleware to provide an openAI compatible endpoint that can call MCP tools

Archive-Agent

Find your files with natural language and ask questions.

kuon

久远：一个开发中的大模型语音助手，当前关注易用性，简单上手，支持对话选择性记忆和Model Context Protocol (MCP)服务。 KUON:A large language model-based voice assistant under development, currently focused on ease of use and simple onboarding. It supports selective memory in conversations and the Model Context Protocol (MCP) service.

leap

Transform any topic into an explainer video with AI narration and 3Blue1Brown-style animations

pydoll

PyDoll MCP Server is a Model Context Protocol (MCP) server built on PyDoll, a next-generation browser automation library. It enables AI assistants like Claude to naturally control web browsers and perform complex web automation tasks.