Telegram Client Library and MCP Server

What is Telegram Client Library and MCP Server?

This project provides both a Telegram client library and an MCP (Model Context Protocol) server for AI assistants to interact with Telegram. It’s for developers who want to build AI-powered tools that can read, search, and manage Telegram channels and messages.

How to use Telegram Client Library and MCP Server?

Set up a .env file with your Telegram API credentials, then run npm install to install dependencies. Start the MCP server with npm start (defaults to port 3000) and connect any MCP‑compatible assistant (e.g., Claude) to the server endpoint. You can also use the standalone client library directly in Node.js scripts.

Key features of Telegram Client Library and MCP Server

• Telegram authentication with 2FA support
• Automatic session reuse and management
• Retrieve chats/dialogs and fetch messages
• Filter messages using regex patterns
• Search Telegram channels by keywords
• List all accessible channels via MCP tools

Use cases of Telegram Client Library and MCP Server

• Have an AI assistant search Telegram channels and retrieve messages on demand
• Build automated monitoring or alerting workflows based on channel content
• Develop custom scripts that interact with Telegram using the client library
• Enable language models to read and analyze Telegram data through a standard MCP interface

FAQ from Telegram Client Library and MCP Server

What are the prerequisites?

You need a Telegram API ID, API hash, and a phone number. These are set in a .env file alongside an optional PORT variable (defaults to 3000).

How does authentication work?

The library handles login (including 2FA) and automatically reuses saved sessions so you don’t need to re‑authenticate each time.

Where is session data stored?

Session files are saved to ./data/session.json by default. You can override this path in the TelegramClient constructor.

Can I use it with AI assistants like Claude?

Yes. The MCP server exposes tools that any MCP‑compatible assistant can call to search channels, list channels, get messages, and filter by pattern.

What transport protocol does the MCP server use?

The server uses an HTTP/SSE transport layer, listening for connections on the configured port.