What is Telegram Mcp

telegram_mcp is a server designed to interact with the Telegram API using the MTProto protocol. It provides a REST API for seamless communication with Telegram services.

Use cases

Use cases for telegram_mcp include building chatbots that respond to user messages, automating message sending for notifications, retrieving chat histories for analysis, and integrating Telegram functionalities into other applications.

How to use

To use telegram_mcp, clone the repository, install the dependencies, configure the .env file with your Telegram API ID and API Hash, and then start the server. You can also run it in development mode for automatic reloading.

Key features

Key features of telegram_mcp include REST API endpoints for checking server status, executing Telegram API methods, retrieving chat lists, fetching messages from chats, sending messages, and listing available API methods.

Where to use

telegram_mcp can be used in various fields such as chatbots, automated messaging systems, data analysis tools, and any application that requires interaction with Telegram services.

Telegram MCP Server

English version | Русская версия

Server for working with Telegram API through Model Context Protocol (MCP). Allows AI agents and other MCP clients to interact with Telegram.

Requirements

• Node.js 14+ (or higher)
• npm
• API ID and API Hash from Telegram

Installation

1. Clone the repository:

   git clone https://github.com/kdoronin/telegram_mcp
   cd telegram-mcp
   

2. Install dependencies:

   npm install
   

   (This will install the necessary packages: gramjs, @modelcontextprotocol/sdk, zod, etc.)

3. Create and configure the .env file:

   # Copy the example .env file
   cp .env.example .env
   

   Edit the .env file and specify your API_ID and API_HASH.

4. Get API ID and API Hash:

   • Go to my.telegram.org
   • Log in to your account
   • Navigate to “API development tools”
   • Create a new application
   • Copy api_id and api_hash to your .env file

Running

Important note about running

The main server file mcp-server.js is located in the project root, which allows running it without path issues.

Option 1: Via npm (recommended)

npm run mcp    # Run from the project root directory

Option 2: Direct node execution

# Run from the project root directory
node mcp-server.js

Option 3: As an executable file

# From the project root
./mcp-server.js

Option 4: After global installation

npm install -g .   # Install the package globally
telegram-mcp       # Run the globally installed package

Integration with MCP clients

Configuration in Cursor

1. Open Cursor settings
2. Go to Features -> MCP Servers
3. Click “Add new MCP server”
4. Configure the server:
   • Name: telegram (or any other)
   • Type: command
   • Command: node /full/path/to/project/mcp-server.js
   • Alternatively: npx telegram-mcp (after global installation)

Configuration in Claude Desktop

1. Open Claude Desktop settings
2. Go to Tools -> MCP
3. Click “Add New Server”
4. Configure the server:
   • Name: telegram (or any other)
   • Type: command
   • Command: node /full/path/to/project/mcp-server.js
   • Alternatively: npx telegram-mcp (after global installation)

Checking functionality

When the server starts:

1. It will load settings from the .env file
2. Check for saved sessions
3. If there are no sessions, it will offer to create a new one (you will need to enter a phone number and confirmation code)

Available Tools

The MCP server provides the following tools:

• getDialogs: Gets a list of user dialogs (chats).
  • Parameters: session (string, required), limit (integer, optional, default: 100).
• getMessages: Gets messages from the specified chat.
  • Parameters: session (string, required), chatId (string, required), limit (integer, optional, default: 100).
• sendMessage: Sends a message to the specified chat.
  • Parameters: session (string, required), chatId (string, required), message (string, required).
• executeMethod: Executes an arbitrary Telegram API method (use with caution).
  • Parameters: session (string, required), method (string, required), params (object, optional).

Note: The session parameter is usually the user’s phone number in international format (e.g., +79001234567).

Usage examples in prompts

Using the telegram.getDialogs tool for session +79001234567, show me the last 5 chats.

With telegram.sendMessage for session +79001234567, send the message "Hello from my AI assistant!" to chat with ID 'username_or_chat_id'.

Authorization

When using a session (phone number) for the first time, the server will request a confirmation code in the console where it is running. Enter the code received from Telegram to authorize the session.

If you have two-factor authentication (2FA) enabled, you will also need to enter your Telegram password. If the password is entered incorrectly, the system will prompt you to enter it again (up to 3 attempts).

After successful authorization, the session will be saved to a file inside the sessions/ directory and will be used for subsequent requests.

Session file structure

Sessions are stored in the sessions/ directory as JSON files named after the phone number (e.g., +79001234567.json). Each file contains:

• A session string (encrypted authorization token)
• A timestamp of creation/update

Troubleshooting

1. Error “Your API ID or Hash cannot be empty or undefined”

   • Check that the .env file is in the project root
   • Make sure API_ID and API_HASH are correctly specified in it
   • Run the server from the project root directory

2. Server doesn’t see the saved session

   • Check the execution path (should be from the project root)
   • Check for the session file in the sessions/ directory
   • Try running with npm run mcp

3. Authorization error

   • If you entered an incorrect 2FA password, the system will prompt you to re-enter it
   • If all attempts are exhausted, delete the session file and try again

Security

• Do not share your API ID and API Hash with third parties.
• Run the server in a trusted environment.
• Session files contain sensitive data. Store them in a secure location and do not share them.
• The executeMethod tool allows executing any Telegram API methods. Use it with caution, as it can perform destructive actions.

License

MIT