Telegram

Fast MCP Telegram Server provides a production-grade bridge between Telegram and your AI assistants, offering secure authentication, flexible transport, robust search, messaging capabilities, and direct API access to Telegram methods. It enables you to manage multiple Telegram accounts and conversations through a unified MCP interface with reliable security guarantees.

How to use

You can use this MCP server by configuring it in your MCP client in either STDIO (local development) or HTTP_AUTH (production) mode. STDIO runs as a local process with environment variables passed to the server, while HTTP_AUTH exposes a remote HTTP endpoint protected by a Bearer token. Use the provided tools to search messages, send and edit messages, read message history, discover chats, and directly invoke MTProto methods.

How to install

Prerequisites: Python 3.8+ and pip must be installed on your system.

Install the MCP server package from PyPI.

pip install fast-mcp-telegram

Authenticate with Telegram using the built-in setup flow. This will guide you through linking your Telegram account and generating a ready-to-use mcp.json.

fast-mcp-telegram-setup --api-id="your_api_id" --api-hash="your_api_hash" --phone-number="+123456789"

Optionally, you can complete authentication in a browser and download the mcp.json file. This file contains your Bearer token and is used by the HTTP_AUTH configuration.

# Example HTTP_AUTH MCP configuration snippet
{
  "mcpServers": {
    "telegram": {
      "url": "https://your-server.com",
      "headers": {
        "Authorization": "Bearer AbCdEfGh123456789KLmnOpQr..."
      }
    }
  }
}

If you prefer STDIO mode for development, start the server with the appropriate environment variables and connect your MCP client to the stdio transport.

Additional sections

Configuration highlights: you can run the server in two modes. STDIO mode runs locally and does not require Bearer token authentication for development. HTTP_AUTH mode exposes a production HTTP endpoint that requires a Bearer token for requests.

Security considerations: Bearer token authentication with session isolation, SSRF protection for file downloads, and structured error handling help ensure safe operation in production.

Notes on usage: you can leverage the HTTP-MTProto Bridge to perform direct Telegram API calls over HTTP with automatic entity resolution and safety guardrails. This enables you to perform actions such as sending messages or retrieving histories using standard HTTP requests.

Notes on demo and quick start usage

A browser-based setup flow is available to authenticate and generate configuration. After completing authentication, you receive a ready-to-use mcp.json containing your Bearer token, which you can reuse in the HTTP_AUTH configuration.

Test the integration quickly by invoking an example message send through the HTTP-MTProto Bridge using the Bearer token you obtained during setup.

Available tools

search_messages_globally

Search across all chats with multi-term queries, date filtering, and chat-type filtering.

search_messages_in_chat

Search within a specific chat, including Saved Messages with optional latest-message query.

send_message

Send new messages with support for file attachments, formatting, and replies.

edit_message

Edit existing messages while preserving formatting and structure.

read_messages

Read specific messages by ID, with batch reading and optional voice transcription for Premium accounts.

find_chats

Find users, groups, or channels using multi-term search and lookup capabilities.

get_chat_info

Get detailed profile information including member counts and online status.

send_message_to_phone

Message phone numbers with optional cleanup and file support.

invoke_mtproto

Direct access to raw MTProto methods with entity resolution and safety guardrails.