fast-mcp-telegram

Purpose

fast-mcp-telegram is a Telegram MCP gateway for AI agents, acting as an intermediary layer between AI agents and the Telegram API. The core problem it solves is: Telegram's native API interfaces are numerous and scattered, making it difficult for AI agents to call them directly and efficiently; this gateway consolidates more than 80 micro APIs into 8 AI-friendly tools, enabling AI assistants to operate Telegram in a more natural way.

Main Capabilities

• Authentication methods: Supports completing authentication by scanning a QR code with the Telegram mobile app (Settings → Devices → Scan QR code), with no need to enter a phone number, no OTP, and no 2FA; it also supports using a phone number as an alternative, or using a Bot Token (no phone number or OTP required).
• Tool set: Exposes 8 context-efficient tools, replacing more than 80 micro APIs.
• Multi-tenant: One server can serve multiple users, with sessions isolated from each other.
• Transport modes: Supports both HTTP and stdio transport modes.
• MTProto bridge: Provides advanced users with raw MTProto direct access capability, callable via curl.
• Files and voice: Supports file attachments and voice transcription.

Usage

1. Installation and authentication
   • Quick path for remote servers: open https://tg-mcp.l1979.ru/setup → scan the QR code → copy the Bearer token.
   • Local CLI path (stdio): run fast-mcp-telegram-setup once to create a Telegram session, then let fast-mcp-telegram provide the service.
   • Bot Token alternative: set the BOT_API_TOKEN environment variable instead of the --phone-number parameter.
2. Configure the MCP client
   • stdio mode (local): add the server to the MCP client configuration (such as claude_desktop_config.json). stdio is the default transport mode for local MCP clients.
   • http-auth mode (remote): add the server to the MCP client configuration; the token is obtained by scanning the QR code on the settings page.
3. Direct API calls (curl): Can be called directly using curl commands; replace with your own TOKEN.
4. Deploy to a remote server: You can deploy your own MCP server on a VDS; see the installation guide for specific steps.

Applicable Scenarios

• Letting an AI assistant operate Telegram via the MCP protocol, for example sending a greeting to your own saved messages.
• Scenarios that require multiple users to share the same Telegram gateway service.
• Advanced users who need to call the raw MTProto API directly.
• Scenarios that need to handle Telegram file attachments and voice transcription.

Limitations and Notes

• Anonymous tool telemetry has been enabled since v0.30.1: a heartbeat is sent every 6 hours, no credentials or message content are collected, and it can be disabled via DO_NOT_TRACK=1 .
• Authentication flow telemetry has been enabled since v0.38.0: atomic events are recorded during setup (phone number, QR code, Bot Token, reauthorization), and the buffer is flushed when the flow is completed.
• Licensed under the MIT License.
• For the specific tool list and detailed documentation, see Tools Reference; for local installation and remote deployment, see Installation Guide; for security features, see the Security documentation.