IQAIcom/mcp-telegram

Telegram MCP Server

Overview

An MCP (Model Context Protocol) server for interacting with Telegram bots and channels using the Telegraf library. This server enables AI agents to send messages, manage channels, forward content, and respond intelligently to Telegram conversations.

By implementing the Model Context Protocol (MCP), this server allows Large Language Models (LLMs) to interact with Telegram directly through their context window, bridging the gap between AI and messaging platforms.

Features

Core Tools

• SEND_MESSAGE: Send messages to channels or chats with optional topic support
• GET_CHANNEL_INFO: Get information about channels/chats
• FORWARD_MESSAGE: Forward messages between chats
• PIN_MESSAGE: Pin messages in channels
• GET_CHANNEL_MEMBERS: Get list of channel administrators

AI Sampling (Enhanced)

• Intelligent Responses: AI-powered responses using FastMCP sampling
• Mention-Only Mode: Smart filtering - responds when mentioned in groups
• Multi-Message Types: Supports text, photos, documents, voice, video, stickers, locations, contacts, polls
• Access Control: Configurable user/chat allow/block lists
• Rate Limiting: Per-user and per-chat rate limiting
• Advanced Configuration: Highly customizable behavior and templates

Installation

Using npx (Recommended)

To use this server without installing it globally:

npx @iqai/mcp-telegram

Build from Source

git clone https://github.com/IQAIcom/mcp-telegram.git
cd mcp-telegram
pnpm install
pnpm run build

Running with an MCP Client

Add the following configuration to your MCP client settings (e.g., claude_desktop_config.json).

Minimal Configuration

{
  "mcpServers": {
    "telegram": {
      "command": "npx",
      "args": ["-y", "@iqai/mcp-telegram"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "your_bot_token_here"
      }
    }
  }
}

Advanced Configuration (Local Build)

{
  "mcpServers": {
    "telegram": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-telegram/dist/index.js"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "your_bot_token_here",
        "SAMPLING_ENABLED": "true",
        "SAMPLING_MENTION_ONLY": "true"
      }
    }
  }
}

Configuration (Environment Variables)

Required

Sampling Configuration

Access Control

Rate Limiting

Message Type Support

Content Filtering

Usage Examples

Market Discovery

• "Send a message to @mychannel saying hello"
• "Get information about @telegram channel"
• "Forward message 123 from @source to @destination"

Bot Commands

• /start: Initialize the bot and get a welcome message
• /help: Get help information about available features
• /config: View current configuration (admin users only)

MCP Tools

FORWARD_MESSAGE

Forward a message from one chat to another

GET_CHANNEL_INFO

Get information about a Telegram channel or chat

GET_CHANNEL_MEMBERS

Get a list of channel administrators and members

PIN_MESSAGE

Pin a message in a Telegram chat or channel

SEND_MESSAGE

Send a message to a Telegram chat or channel

Development

Build Project

pnpm run build

Development Mode (Watch)

pnpm run watch

Linting & Formatting

pnpm run lint
pnpm run format

Project Structure

• src/tools/: Individual tool definitions
• src/services/: Telegram service and bot logic
• src/sampling/: AI sampling feature implementation
• src/config.ts: Configuration with Zod validation
• src/index.ts: Server entry point

Getting Your Bot Token

1. Message @BotFather on Telegram
2. Use /newbot command
3. Follow the prompts to create your bot
4. Copy the bot token provided
5. Set it as an environment variable

Resources

• Telegram Bot API Documentation
• Model Context Protocol (MCP)
• Telegraf Documentation

Disclaimer

This project is an unofficial tool. Users should ensure their bot usage complies with Telegram's Terms of Service and Bot API policies.

License