Kfastov Telegram MCP Server

🚀 Telegram Client Library and MCP Server

This project provides a Telegram client library and an MCP (Model Context Protocol) server for AI assistants to interact with Telegram.

🚀 Quick Start

This project offers a Telegram client library and an MCP server, enabling seamless interaction between AI assistants and Telegram.

✨ Features

Telegram Client Library

• Authentication: Supports logging in with a Telegram account (including two-factor authentication).
• Session Management: Automatically reuses existing sessions.
• Retrieve Chats/Groups: Retrieves information about all chats and groups.
• Fetch Messages: Fetches messages from specific groups or chats.
• Filter Messages by Pattern: Filters messages using regular expressions or other rules.

MCP Server

• Search Channels: Searches for channels by keywords in their names.
• List Available Channels: Views all accessible channels.
• Fetch Channel Messages: Fetches messages from any accessible channel.
• Filter Messages by Pattern: Filters messages using regular expressions.

📦 Installation

1. Create a .env file and add 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, default is 3000 (MCP server)

2. Install dependencies:

npm install

💻 Usage Examples

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
  );

  // Log in to Telegram
  await client.login();

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

  // Print information about all chats/groups
  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:

npm start

2. The MCP server will run at the following address:

http://localhost:3000/mcp

3. You can test the MCP server using the provided client:

npm run mcp-client

For detailed information about the MCP server, refer to MCP-README.md. For the code structure, refer to CODE_STRUCTURE.md.

📚 Documentation

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) The path to store the session file (default: './data/session.json').

Methods

• login(): Logs in to the Telegram account.
• getDialogs(): Retrieves information about all chats and groups.
• getMessageById(id): Fetches a specific message by its ID.
• sendMessage(chatId, text): Sends a message to a specified chat.
• filterMessages(pattern): Filters messages using a regular expression.

🔧 Technical Details

The main files in the project include:

1. telegram-client.js: The core implementation of the Telegram client library.
2. mcp-server.js: The main logic of the MCP server.
3. README.md: Project documentation and usage instructions.
4. .env: Environment variable configuration file.
5. package.json: Project dependency management file.

🛠️ Integration and Extension

This library is designed to integrate with other AI assistants (such as Claude), allowing these assistants to interact with and process messages via Telegram. You can extend its functionality through custom logic.

📄 License

This project is licensed under the MIT License. For details, please refer to the LICENSE file.