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