local-only server

The server can only run on the client’s local machine because it depends on local resources.

Integrations

Handles configuration management through environment variables, specifically for storing Telegram API credentials including API ID, API hash, and phone number.
Enables interaction with Telegram messaging platform, providing tools to search channels by keywords, list available channels, retrieve messages from channels, and filter messages by regex patterns.

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.

Features

Telegram Client Library

Authentication with Telegram (including 2FA support)
Session management (automatic reuse of existing sessions)
Retrieving chats/dialogs
Fetching messages from specific chats
Filtering messages by pattern (e.g., regex)

MCP Server

Search channels by keywords - Find Telegram channels by searching for keywords in their names
List available channels - View all accessible channels
Get messages from channels - Retrieve messages from any accessible channel
Filter messages by pattern - Apply regex patterns to filter messages

Setup

Create a .env file with your Telegram API credentials:

TELEGRAM_API_ID=your_api_id
TELEGRAM_API_HASH=your_api_hash
TELEGRAM_PHONE_NUMBER=your_phone_number
PORT=3000  # Optional, defaults to 3000 for MCP server

Install dependencies:

npm install

Usage

Using the Telegram Client Library

const TelegramClient = require("./telegram-client");
const dotenv = require("dotenv");

dotenv.config();

async function main() {
  // Create a new client instance
  const client = new TelegramClient(
    process.env.TELEGRAM_API_ID,
    process.env.TELEGRAM_API_HASH,
    process.env.TELEGRAM_PHONE_NUMBER
  );

  // Login to Telegram
  await client.login();

  // Get all chats/dialogs
  const { chats } = await client.getDialogs();

  // Print all chats
  chats.forEach((chat) => {
    if (chat.title) {
      console.log(`Chat: ${chat.title}`);
    }
  });
}

main().catch(console.error);

Run the example client:

npm run client

Using the MCP Server

Start the MCP server:

npm start

The MCP server will be available at:

http://localhost:3000/mcp

You can test the MCP server using the included client:

npm run mcp-client

For more details about the MCP server, see MCP-README.md.
For information about the code architecture, see CODE_STRUCTURE.md.

API Reference

TelegramClient

Constructor

const client = new TelegramClient(apiId, apiHash, phoneNumber, sessionPath);

apiId: Your Telegram API ID
apiHash: Your Telegram API Hash
phoneNumber: Your phone number in international format
sessionPath: (Optional) Path to save the session file (default: './data/session.json')

Methods

login(): Authenticates with Telegram (handles both new logins and session reuse)
getDialogs(limit, offset): Gets a list of dialogs (chats)
getChatMessages(chat, limit): Gets messages from a specific chat
filterMessagesByPattern(messages, pattern): Filters an array of messages by a regex pattern
hasSession(): Checks if a valid session exists

Files in this Repository

telegram-client.js: The main client library
client.js: An example client with additional helper functions
index.js: Original example using the client library
mcp-server.js: The MCP server main entry point
telegram-mcp.js: The MCP server implementation with Telegram tools
http-server.js: The HTTP/SSE server transport layer
mcp-client-example.js: A simple client to test the MCP server

Using with Claude or other MCP-compatible Assistants

The MCP server can be used with Claude or other MCP-compatible assistants. When connected, the assistant will have access to your Telegram channels and messages through the tools provided by the server.

Example workflow:

Start the MCP server
Connect Claude to the MCP server using the MCP URL
Ask Claude to search for channels, retrieve messages, or filter messages by pattern

License

MIT

This server cannot be installed

-

security - not tested

F

license - not found

-

quality - not tested

A Model Context Protocol server that enables AI assistants to interact with Telegram, allowing them to search channels, list available channels, retrieve messages, and filter messages by regex patterns.

Related Resources

Reddit Discussion about this server

Telegram MCP Server