Telegram
About
# Telegram MCP Server English version | [Русская версия](README_RU.md) 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…
Explore
- Reads dialogs and messages from your Telegram account.
- Sends messages to any chat or user.
- Executes arbitrary Telegram API methods via executeMethod.
- Saves authenticated sessions locally for reuse.
- Supports two-factor authentication (2FA).
- Integrates easily with MCP clients like Cursor and Claude Desktop.
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
TelegramCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
- Node.js 14+ (or higher)
- npm
- API ID and API Hash from Telegram
The main server file mcp-server.js is located in the project root, which allows running it without path issues.
npm install -g . # Install the package globally
telegram-mcp # Run the globally installed package
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)
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)
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'.
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).
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"telegram": {
"Telegram": {
"command": "node",
"args": [
"/Users/dka/Documents/Solo/git/telegram_mcp/mcp-server.js"
]
}
}
}
}McpServers
{
"Telegram": {
"command": "node",
"args": [
"/Users/dka/Documents/Solo/git/telegram_mcp/mcp-server.js"
]
}
}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
```bash
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
