Telegram MCP Server

MCP server for interacting with Telegram via the Telegram Bot API. The server provides an LLM client with a set of tools for sending messages, reading the latest available messages, and retrieving chat information.

Features

The server provides three MCP tools:

• send_message — sends a text message to a specified Telegram chat.

• get_recent_messages — retrieves the latest available messages from a specified chat.

• get_chat_info — returns basic information about a Telegram chat.

The server uses stdio transport, so it can be connected to MCP Inspector and other MCP clients without a separate HTTP server.

Related MCP server: agent-telegram-mcp

Architecture

MCP client / MCP Inspector
            │
            │ MCP over stdio
            ▼
      src/server.py
            │
            ▼
   src/telegram_client.py
            │
            │ HTTPS
            ▼
    Telegram Bot API

server.py handles the MCP interface and tool registration.

telegram_client.py encapsulates HTTP interaction with the Telegram Bot API.

config.py loads the token from an environment variable.

Stack

• Python 3.10+

• MCP Python SDK 2.x

• Telegram Bot API

• httpx

• python-dotenv

Project Structure

telegram-mcp/
├── src/
│   ├── __init__.py
│   ├── config.py
│   ├── telegram_client.py
│   └── server.py
├── .env.example
├── .gitignore
├── requirements.txt
└── README.md

Requirements

• Python 3.10 or later

• A Telegram bot created via @BotFather

• Node.js and npx — only if using MCP Inspector via mcp dev

Installation

Clone the repository and navigate to its directory:

git clone <repository-url>
cd telegram-mcp

Create a virtual environment:

python3 -m venv .venv
source .venv/bin/activate

Install dependencies:

pip install -r requirements.txt

Setting Up a Telegram Bot

1. Open Telegram and find @BotFather.

2. Execute /newbot.

3. Create a bot and obtain the Bot API token.

4. Do not add the token to the source code or Git.

Create a .env file:

cp .env.example .env

Specify the token:

TELEGRAM_BOT_TOKEN=your_telegram_bot_token_here

.env is added to .gitignore.

Chat Preparation

Private Chat

1. Open the created bot.

2. Click Start or send it a message.

3. To test get_recent_messages, send several text messages.

Group

1. Create a test group.

2. Add the bot to the group.

3. If the bot needs to see regular group messages, disable its privacy mode via @BotFather (/setprivacy → Disable).

4. Send several messages to the group.

To obtain a chat_id, it is convenient to first call get_chat_info or get_recent_messages after the bot has received a message from the desired chat.

Running

From the project root directory:

python src/server.py

The server runs via stdio and expects an MCP connection. Therefore, the absence of standard terminal output after startup is normal behavior.

For development and testing, you can use the MCP CLI:

mcp dev src/server.py

The command launches the server and MCP Inspector. Inspector uses npx, so Node.js must be available in PATH.

MCP tools

send_message

Sends a text message to Telegram.

Parameters:

chat_id: string — ID чата
text: string — текст сообщения

Example:

chat_id: 123456789
text: Привет! Сообщение отправлено через MCP.

The server returns a confirmation of sending and the message_id.

get_recent_messages

Retrieves the latest available messages from a specified chat.

Parameters:

chat_id: string — ID чата
limit: integer — количество сообщений, по умолчанию 10

limit is constrained to a range from 1 to 100.

Example:

chat_id: 123456789
limit: 10

The result includes the sender and text of each available message.

get_chat_info

Retrieves basic information about a chat.

Parameters:

chat_id: string — ID чата

The response displays available fields, including ID, type, title, username, first name, and last name.

How Message Retrieval Works

The Telegram Bot API does not provide a bot with a separate method for reading an arbitrary chat history. To receive incoming messages, the server uses getUpdates.

get_recent_messages requests up to 100 of the latest available updates and then filters them by chat_id. Therefore, the tool works with messages that Telegram provides to the bot through the updates queue, not with the full chat history.

This means the tool is not a replacement for a Telegram client with access to the entire message history. For testing, it is sufficient to send messages after adding the bot to the chat and then call get_recent_messages.

Important: getUpdates is not used simultaneously with an active webhook. If a webhook is configured for the bot, first remove it so that long polling via getUpdates can receive updates.

Example Scenario

1. Launch MCP Inspector.

2. Connect src/server.py.

3. Ensure the following are available:

   • send_message

   • get_recent_messages

   • get_chat_info

4. Call get_chat_info to verify the connection to the chat.

5. Call send_message and confirm the message appears in Telegram.

6. Send a few messages in Telegram.

7. Call get_recent_messages and verify the received message list.

Security

The Telegram Bot API token is transmitted only through the TELEGRAM_BOT_TOKEN environment variable.

The actual .env file must not be committed to Git. Only .env.example without a working token is stored in the repository.

Limitations

• The bot does not have access to the entire Telegram chat history via the Bot API.

• get_recent_messages works with available bot updates.

• In groups, the set of messages the bot receives depends on Telegram's privacy settings.

• getUpdates and webhook are mutually exclusive methods for receiving updates.