Telegram MCP Server

⚠️ Disclaimer: This project contains AI-generated code that has not been thoroughly tested. Use at your own risk and verify all functionality before production deployment.

A Model Context Protocol (MCP) server that enables AI assistants to send messages to Telegram users. Features a web-based configuration interface and supports both chat IDs and usernames.

Features

• MCP Tool: send_telegram_message tool for AI assistants

• Default User Support: Send messages to a configured default user when no recipient is specified

• Web Interface: Easy configuration and testing via web browser

• Flexible Recipients: Support for both Telegram chat IDs and usernames

• Real-time Status: Live status monitoring of server and bot configuration

Related MCP server: Telegram Bot MCP

Prerequisites

• Node.js 18 or higher

• A Telegram bot token from @BotFather

Quick Start

1. Create a Telegram Bot

1. Open Telegram and search for @BotFather

2. Start a chat and send the command /newbot

3. Follow the prompts to:

   • Choose a name for your bot

   • Choose a username for your bot (must end with bot)

4. Copy the API token provided by BotFather

2. Install and Configure

# Clone or download this repository
git clone <repository-url>
cd telegram-mcp-server

# Install dependencies
npm install

# Copy environment template
cp .env.example .env

# Edit .env file with your bot token
# TELEGRAM_BOT_TOKEN=your_bot_token_here

3. Start the Server

# Start the server
npm start

The web interface will be available at http://localhost:3000

4. Configure via Web Interface

1. Open http://localhost:3000 in your browser

2. Enter your bot token in the configuration section

3. Optionally set a default user (chat ID or username)

4. Click "Save Configuration"

5. Test the Bot

1. In the web interface, go to the "Test Message Sending" section

2. Enter a test message

3. Optionally specify a recipient (leave empty to test default user)

4. Click "Send Test Message"

Configuration

Primary Configuration: MCP Servers GUI (Recommended)

Configuration should be managed through Cursor's MCP Servers settings:

1. Open Cursor Settings (Ctrl+, or Cmd+,)

2. Search for "MCP" or navigate to MCP Servers settings

3. Add or edit the telegram server configuration

4. Set environment variables:

   • TELEGRAM_BOT_TOKEN (required): Your bot token from @BotFather

   • TELEGRAM_DEFAULT_USER (optional): Default chat ID or username for messages

Configuration Priority:

1. Primary: Environment variables from MCP Server configuration (Cursor GUI) - used at startup

2. Secondary: Runtime updates via web interface API - for testing/debugging only

Stored Values as Defaults:

• When tool calls don't provide chatId or username, the stored TELEGRAM_DEFAULT_USER is used automatically

• If TELEGRAM_DEFAULT_USER is not configured and no recipient is provided, an error is returned

Web Interface Configuration (Testing/Debugging)

The web interface (http://localhost:3000) allows runtime configuration changes for testing:

• Bot Token: Enter your Telegram bot token (runtime only)

• Default User: Set a fallback recipient when no user is specified in messages

  • Use chat ID (numeric) for reliability

  • Username can be used but requires the user to have started your bot

⚠️ Note: Web interface configuration is temporary and for testing purposes. For persistent configuration, use Cursor's MCP Servers GUI.

Legacy: Environment Variables File

For standalone usage (not via MCP), you can create a .env file:

# Required: Your bot token from BotFather
TELEGRAM_BOT_TOKEN=your_bot_token_here

# Optional: Default user for messages (chat ID or username)
TELEGRAM_DEFAULT_USER=123456789

# Optional: Web interface port (default: 3000)
WEB_PORT=3000

Usage with MCP Clients

Connecting to Cursor

1. Build the project:

   npm run build

2. Configure in Cursor's MCP Servers GUI:

   • Open Cursor Settings (Ctrl+, or Cmd+,)

   • Search for "MCP Servers" or navigate to MCP settings

   • Add a new server or edit existing:

     • Name: telegram

     • Command: node

     • Arguments: C:\AppDev\Projects\MsgMCP\dist\index.js (use your full path)

     • Environment Variables:

       • TELEGRAM_BOT_TOKEN: Your bot token from @BotFather

       • TELEGRAM_DEFAULT_USER: (Optional) Default chat ID or username

3. Restart Cursor for changes to take effect

Cursor AI Notification Rule

Purpose: Ensure the user is promptly notified whenever user intervention is required.

Triggers:

• Completion of the process with a success message

• Any unexpected halts or issues in the process

• When Cursor AI requires user input or has questions

Action: Utilize send_telegram_message tool to send a detailed Telegram message to the user.

Connecting to Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "telegram": {
      "command": "node",
      "args": ["/path/to/telegram-mcp-server/dist/index.js"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "your_bot_token_here",
        "TELEGRAM_DEFAULT_USER": "your_default_user"
      }
    }
  }
}

Using the Tool

The server provides one MCP tool: send_telegram_message

Parameters

• message (required): The text message to send to the default user

Examples

Send to default user:

Send a message saying "Hello from AI!"

The tool automatically sends to the TELEGRAM_DEFAULT_USER configured in the .env file. No recipient specification needed!

Simple usage:

Tell the user that the task is complete

Notify that the server is running

API Endpoints

The server exposes a REST API for configuration and testing:

GET /api/status

Get server and bot status information.

Response:

{
  "server": "running",
  "bot": "initialized",
  "config": {
    "hasToken": true,
    "hasDefaultUser": true
  }
}

GET /api/config

Get current configuration (masked for security).

Response:

{
  "telegramBotToken": "configured",
  "telegramDefaultUser": "123456789",
  "webPort": 3000
}

POST /api/config

Update configuration.

Request:

{
  "telegramBotToken": "new_token_here",
  "telegramDefaultUser": "new_default_user"
}

POST /api/test

Send a test message.

Request:

{
  "message": "Test message",
  "chatId": "123456789",
  "username": "@testuser"
}

Development

Build

npm run build

Development Mode

npm run dev

Run Web Interface Only

npm run web

Troubleshooting

Bot Not Sending Messages

1. Check Bot Token: Ensure your bot token is correct and the bot is not revoked

2. User Interaction: For username-based sending, the user must have started your bot first

3. Chat ID vs Username: Use chat IDs for more reliable message delivery

Web Interface Not Loading

1. Port Conflict: Check if port 3000 is available

2. Firewall: Ensure the port is not blocked by firewall

3. Environment: Verify Node.js version and dependencies

MCP Connection Issues

1. Path: Ensure the path to dist/index.js is correct in your MCP client config

2. Environment Variables: Make sure required environment variables are set

3. Build: Ensure the project is built (npm run build) before connecting

Security Considerations

• Store bot tokens securely and never commit them to version control

• The web interface is intended for local configuration only

• Consider additional authentication for production deployments

• Bot tokens have full access to your bot - keep them confidential

License

MIT License

Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Test thoroughly

5. Submit a pull request

Support

For issues and questions:

1. Check the troubleshooting section above

2. Review the Telegram Bot API documentation

3. Check MCP documentation for client integration

Changelog

v1.0.0

• Initial release

• MCP server with Telegram messaging tool

• Web-based configuration interface

• Support for chat IDs and usernames

• Default user fallback functionality