telegram-mcp
If you are the rightful owner of telegram-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
A Model Context Protocol (MCP) server that enables LLMs to send notifications via Telegram and receive user responses.
Telegram MCP Server
A Model Context Protocol (MCP) server that enables LLMs to send notifications via Telegram and receive user responses.
Features
- Send text notifications to a Telegram chat with customizable urgency levels
- Wait for and retrieve user responses
- Integrates with Cline and other MCP-compatible LLM applications
Prerequisites
- Node.js 16 or higher
- A Telegram bot token (obtained from @BotFather)
- Your Telegram chat ID
Installation
From npm (recommended)
npm install -g telegram-mcp
From GitHub
git clone https://github.com/CHarrisTech/telegram-mcp.git
cd telegram-mcp
npm install
npm run build
Configuration
The server requires two environment variables:
TELEGRAM_BOT_TOKEN: Your Telegram bot tokenTELEGRAM_CHAT_ID: Your Telegram chat ID
Getting a Telegram Bot Token
- Start a chat with @BotFather on Telegram
- Send the command
/newbot - Follow the instructions to create a new bot
- BotFather will provide you with a token for your new bot
Finding Your Chat ID
- Start a chat with your new bot
- Send a message to the bot
- Visit
https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates - Look for the
chatobject in the response and note theidfield
Usage
Running Standalone
# Set environment variables
export TELEGRAM_BOT_TOKEN="your_bot_token"
export TELEGRAM_CHAT_ID="your_chat_id"
# Run the server
telegram-mcp
Integrating with Cline
Add the following to your Cline MCP settings file:
{
"mcpServers": {
"telegram-mcp": {
"command": "node",
"args": ["path/to/telegram-mcp/build/index.js"],
"env": {
"TELEGRAM_BOT_TOKEN": "your_bot_token",
"TELEGRAM_CHAT_ID": "your_chat_id"
},
"disabled": false,
"autoApprove": []
}
}
}
Integrating with Claude Desktop
Add the following to your Claude Desktop config file:
{
"mcpServers": {
"telegram-mcp": {
"command": "node",
"args": ["path/to/telegram-mcp/build/index.js"],
"env": {
"TELEGRAM_BOT_TOKEN": "your_bot_token",
"TELEGRAM_CHAT_ID": "your_chat_id"
},
"disabled": false,
"autoApprove": []
}
}
}
Available Tools
send_notification
Sends a notification message to the configured Telegram chat.
Parameters:
message(required): The message to send to the userproject(required): The name of the project the LLM is working onurgency(optional): The urgency level ("low", "medium", or "high")
check_notification_response
Checks if the user has responded to a previously sent notification.
Parameters:
message_id(required): The ID of the message to check for responsestimeout_seconds(optional): How long to wait for a response before giving up (default: 30)
Development
# Clone the repository
git clone https://github.com/CHarrisTech/telegram-mcp.git
cd telegram-mcp
# Install dependencies
npm install
# Build the project
npm run build
# Watch for changes during development
npm run watch
# Test with the MCP Inspector
npm run inspector
Testing Locally
The repository includes scripts to help you test the server locally:
Windows
# Set environment variables
set TELEGRAM_BOT_TOKEN=your_bot_token
set TELEGRAM_CHAT_ID=your_chat_id
# Run the test script
test-server.bat
macOS/Linux
# Set environment variables
export TELEGRAM_BOT_TOKEN=your_bot_token
export TELEGRAM_CHAT_ID=your_chat_id
# Make the script executable (first time only)
chmod +x test-server.sh
# Run the test script
./test-server.sh
Examples
The examples directory contains sample code demonstrating how to use the Telegram MCP server:
programmatic-usage.js: Shows how to use the server programmatically in your own Node.js applications
To run an example:
# Set required environment variables
export TELEGRAM_BOT_TOKEN="your_bot_token"
export TELEGRAM_CHAT_ID="your_chat_id"
# Run the example
node examples/programmatic-usage.js
License
MIT
