Telegram MCP Server

🚀 Telegram MCP Server

A MCP (Multipurpose Control Protocol) server that allows AI assistants (such as Claude) to interact with your Telegram account through the user client API (instead of the bot API). This server is built on the @mtproto/core and FastMCP frameworks.

🚀 Quick Start

This server enables AI assistants to interact with your Telegram account via the user client API. Here's a brief guide to get you started:

Prerequisites

1. Node.js: It is recommended to use version 18 or higher.
2. Telegram Account:
   • You need an active Telegram account.
   • Two-step verification (2FA) must be enabled (Settings → Privacy and Security → Two-step verification).
3. Telegram API Credentials:
   • Obtain api_id and api_hash here.

Installation

1. Clone this repository:

   git clone https://github.com/kfastov/telegram-mcp-server.git
   cd telegram-mcp-server
   

2. Install dependencies:

   npm install
   

Configuration

Server Configuration

Edit the config.json file and set the following parameters:

{
  "telegram": {
    "api_id": "YOUR_API_ID",
    "api_hash": "YOUR_API_HASH"
  },
  "port": 8080,
  "session_name": "mcp_session"
}

Environment Variables

You can also set the following parameters via environment variables:

• TELEGRAM_API_ID: Replace with your api_id.
• TELEGRAM_API_HASH: Replace with your api_hash.
• PORT: The port on which the server runs (default: 8080).
• SESSION_NAME: The session name (default: mcp_session).

Running

1. Start manually:

   node index.js
   

2. Run in the background using PM2:

   pm2 start index.js --save
   

✨ Features

Tools

• listChannels

  • Lists Telegram channels/chats accessible to the current account, based on the server cache.
  • Parameters:
    • limit (number, optional): The maximum number of channels to return (default: 50).
  • Output: A list of channels/chats containing ID, title, type, and access hash (if applicable).

• searchChannels

  • Searches for channels/chats in the cache based on keywords in the name.
  • Parameters:
    • keywords (string): The keywords to search for in the channel name.
    • limit (number, optional): The maximum number of results to return (default: 100).
  • Output: A list of matching channels/chats.

• getChannelMessages

  • Retrieves recent messages from a specific channel/chat using its ID.
  • Parameters:
    • channelId (number): The numerical ID of the channel/chat (obtained via listChannels or searchChannels).
    • limit (number, optional): The maximum number of messages to return (default: 100).
    • filterPattern (string, optional): A JavaScript-compatible regular expression for filtering messages based on text content.
  • Output: A list of messages containing ID, date, text, and sender ID.

📚 Documentation

Troubleshooting

• Login Prompt: If the server continuously requests a login code/password when the MCP client starts, ensure that the data/session.json file exists and is valid. You may need to manually run node index.js to refresh the session.
• Cache Issue: If channels seem outdated or missing, you can delete the ./data/dialog_cache.json file and restart the server (manually run node index.js) to force a refresh. This may take some time.
• Module Not Found: Ensure that npm install has been run in the project directory. If the MCP client starts the server, make sure the working directory is set correctly or use an absolute path.

Telegram Client Library

This repository also contains the underlying telegram-client.js library for building the MCP server. For more details, please refer to LIBRARY.md.

📄 License

This project is released under the MIT License. See the LICENSE file for details.