What is Telegram Mcp

telegram-mcp is a Model Context Protocol (MCP) server that allows Large Language Models (LLMs) to send notifications via Telegram and receive user responses.

Use cases

Use cases include sending alerts for project updates, receiving user feedback, and facilitating communication between LLMs and users in real-time.

How to use

To use telegram-mcp, install it via npm or clone it from GitHub. Set the required environment variables for the Telegram bot token and chat ID, then run the server. You can also integrate it with applications like Cline and Claude Desktop.

Key features

Key features include sending text notifications with customizable urgency levels, waiting for and retrieving user responses, and integration with other MCP-compatible LLM applications.

Where to use

telegram-mcp can be used in various fields such as customer support, automated notifications, and interactive user engagement through Telegram.

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 token
• TELEGRAM_CHAT_ID: Your Telegram chat ID

Getting a Telegram Bot Token

1. Start a chat with @BotFather on Telegram
2. Send the command /newbot
3. Follow the instructions to create a new bot
4. BotFather will provide you with a token for your new bot

Finding Your Chat ID

1. Start a chat with your new bot
2. Send a message to the bot
3. Visit https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates
4. Look for the chat object in the response and note the id field

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 user
• project (required): The name of the project the LLM is working on
• urgency (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 responses
• timeout_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