Telegram MCP Server for AI Assistants

Overview

The Telegram MCP Server is a powerful implementation that combines a Telegram client library with an MCP (Model Context Protocol) server. This project enables AI assistants to interact with Telegram, providing features like message retrieval, channel search, and pattern-based filtering.

Features

Telegram Client Library

• Authentication: Supports Telegram login, including 2FA.
• Session Management: Automatically reuses existing sessions.
• Chat Management: Retrieve chats/dialogs and fetch messages from specific chats.
• Message Filtering: Filter messages using regex patterns.

MCP Server

• Channel Search: Find Telegram channels by keywords in their names.
• Channel Listing: View all accessible channels.
• Message Retrieval: Fetch messages from any accessible channel.
• Pattern Filtering: Apply regex patterns to filter messages.

Setup

1. Create a .env file with your Telegram API credentials:
   env 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

2. Install dependencies:
   shell npm install

Usage

Using the Telegram Client Library

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

dotenv.config();

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

  await client.login();

  const { chats } = await client.getDialogs();

  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

1. Start the MCP server:
   shell npm start

2. The MCP server will be available at:
   http://localhost:3000/mcp

3. Test the MCP server using the included client:
   shell npm run mcp-client

For more details, see MCP-README.md and CODE_STRUCTURE.md.

API Reference

TelegramClient

Constructor

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

Methods

• login(): Authenticates with Telegram.
• getDialogs(limit, offset): Gets a list of dialogs (chats).
• getChatMessages(chat, limit): Gets messages from a specific chat.
• filterMessagesByPattern(messages, pattern): Filters 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 integrated with Claude or other MCP-compatible assistants. Once connected, the assistant can access Telegram channels and messages through the server.

Example Workflow

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

License

MIT

About

This project provides an MCP server implementation for Telegram, enabling AI assistants to interact with Telegram channels and messages efficiently.