Telegram Bot MCP

A FastMCP server that exposes Telegram Bot API operations as Model Context Protocol (MCP) tools. The server uses aiogram for Telegram Bot API calls and pydantic-settings for environment-based configuration.

Requirements

• Python 3.10 or newer

• A Telegram bot token from BotFather

• An MCP-compatible client that can connect over streamable-http, sse, or stdio

Related MCP server: telegram-mcp-kit

Installation

1. Clone or download this project.

2. Install dependencies.

   pip install -r requirements.txt

3. Create your environment file.

   cp .env.example .env

   On Windows PowerShell:

   Copy-Item .env.example .env

4. Edit .env as needed for server transport, logging, and safety limits. (logging and safety limits currently not working)

Running the server

Run from the project root:

python telegram_bot_mcp.py

The default transport is streamable-http on 127.0.0.1:51000.

You can override transport, host, and port with command-line arguments:

python telegram_bot_mcp.py --transport streamable-http --host 127.0.0.1 --port 51000

Supported transport values are:

• streamable-http

• sse

• stdio

MCP client configuration example

For a client that launches the server with a command, use a configuration similar to:

{
  "mcpServers": {
    "telegram-bot-mcp": {
      "command": "python",
      "args": ["telegram_bot_mcp.py", "--transport", "stdio"]
    }
  }
}

For HTTP-based clients, start the server with streamable-http and configure the client to connect to:

http://127.0.0.1:51000/mcp

Supported MCP tools

Server tools

User and bot identity tools

Chat tools

Message tools

Telegram Bot API limitations

Telegram bots can only perform actions allowed by the Telegram Bot API and the bot's permissions in each chat. In particular:

• The bot must be a member of the target chat.

• Administrative permissions may be required for deleting messages or forum topics.

• The Telegram Bot API cannot enumerate an entire chat history for deletion.

• Message deletion is best-effort and may fail for messages the bot is not allowed to delete.