MCP Telegram

• Package: @iqai/mcp-telegram
• Purpose: Interacting with Telegram bots and channels using the Telegraf library.

Usage with ADK TypeScript

import {McpTelegram} from "@iqai/adk";

const toolset = McpTelegram({
  env: {
    TELEGRAM_BOT_TOKEN: process.env.TELEGRAM_BOT_TOKEN,
  },
})

const tools = await toolset.getTools()

import {McpToolset} from "@iqai/adk";

const toolset = new McpToolset({
  name: "Telegram MCP Client",
  description: "Client for Telegram bot operations",
  transport: {
    mode: "stdio",
    command: "pnpm",
    args: ["dlx", "@iqai/mcp-telegram"],
    env: {
      TELEGRAM_BOT_TOKEN: process.env.TELEGRAM_BOT_TOKEN,
      PATH: process.env.PATH || "",
    },
  },
})

const tools = await toolset.getTools()

{
  "mcpServers": {
    "telegram-mcp-server": {
      "command": "pnpm",
      "args": ["dlx", "@iqai/mcp-telegram"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "your_bot_token_here"
      }
    }
  }
}

Features

• Provides tools to send messages, get channel information, forward messages, pin messages, and get channel members.
• Uses the Telegraf library, a modern and feature-rich Telegram bot framework for Node.js.

Available Tools

The server exposes the following tools that MCP clients can utilize:

SEND_MESSAGE

Send a message to a Telegram chat or channel.

• Parameters: chatId (string), text (string), parseMode (string, optional), disableWebPagePreview (boolean, optional), disableNotification (boolean, optional)

GET_CHANNEL_INFO

Get information about a channel or chat.

• Parameters: channelId (string)

FORWARD_MESSAGE

Forward a message from one chat to another.

• Parameters: fromChatId (string), toChatId (string), messageId (string), disableNotification (boolean, optional)

PIN_MESSAGE

Pin a message in a chat or channel.

• Parameters: chatId (string), messageId (string), disableNotification (boolean, optional)

GET_CHANNEL_MEMBERS

Get channel administrators (limited by Telegram API).

• Parameters: channelId (string), limit (number, optional)

Sampling

Sampling enables an mcp server to request llm sampling (generations or completions) from the client. The mcp-telegram server listens to new messages and uses sampling to get llm responses and responds to them, basically in a nutshell allowing for bi-directional communication.

This is useful when you want agentic capabilities ie building a telegram bot that can respond to messages and also send messages to other users.

Resources

• An example telegram bot written with adk-ts that makes use of sampling: Telegram bot example
• For more info on sampling please refer to: MCP Sampling

Environment Variables

• TELEGRAM_BOT_TOKEN: Your Telegram bot token (required)

Usage Examples

SEND_MESSAGE

Send a message to a Telegram channel:

{
  "tool_name": "SEND_MESSAGE",
  "arguments": {
    "chatId": "@mychannel",
    "text": "Hello from the Telegram MCP Server!"
  }
}

GET_CHANNEL_INFO

Get information about a Telegram channel:

{
  "tool_name": "GET_CHANNEL_INFO",
  "arguments": {
    "channelId": "@mychannel"
  }
}

Response Examples

SEND_MESSAGE

Successful response:

{
  "success": true,
  "result": "Message sent successfully!\n\nMessage ID: 123\nChat ID: @mychannel\nSent at: 2024-03-15T12:34:56.789Z\nText: Hello from the Telegram MCP Server!"
}

GET_CHANNEL_INFO

Successful response:

{
  "success": true,
  "result": "Channel Information:\n\nTitle: My Channel\nID: -1001234567890\nType: channel\nUsername: mychannel\nDescription: This is my Telegram channel.\nMember Count: 1234"
}

Error Handling

The tools will return an error message in the result field if an error occurs. Common errors include:

• Missing bot token: Ensure the TELEGRAM_BOT_TOKEN environment variable is set.
• Invalid chat ID: Double-check the chat ID or username.
• Bot not in channel: Add the bot to the channel with appropriate permissions.

Deployment Issues

Render Deployment Failure with Telegram Polling

When deploying Telegram polling-based agents to Render using Docker, the deployment may fail because:

• Render Web Services require binding to $PORT environment variable
• Telegram polling agents don't bind to an HTTP port (they use Telegram's polling API)
• The service appears unhealthy without a bound port and may be restarted or terminated

Solution: Switch the service type to "Background Worker" on Render instead of "Web Service". Background Workers are designed for long-running processes that don't need to expose HTTP endpoints, which matches Telegram polling behavior.

For more details, see GitHub Issue #345.

Bot Setup

1. Create a bot with @BotFather
2. Get your bot token
3. Add your bot to channels with appropriate permissions
4. Use channel usernames (e.g., @mychannel) or chat IDs for interactions