Skip to main content
Glama
Telegram MCP Server

Telegram MCP Server

by BrainDAO

Telegram MCP Server

npm version License: MIT

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.

Related MCP server: mcp-telegram

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

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

Variable

Required

Description

TELEGRAM_BOT_TOKEN

Yes

Your Telegram bot token from @BotFather

Sampling Configuration

Variable

Default

Description

SAMPLING_ENABLED

true

Enable/disable AI sampling entirely

SAMPLING_MENTION_ONLY

true

Only respond when mentioned in groups

SAMPLING_RESPOND_TO_DMS

true

Always respond in DMs

SAMPLING_MAX_TOKENS

1000

Max tokens per AI response

SAMPLING_SHOW_TYPING

true

Show typing indicator

SAMPLING_SILENT_MODE

false

Log but don't respond

Access Control

Variable

Default

Description

SAMPLING_ALLOWED_CHATS

""

Comma-separated chat IDs/usernames to allow (empty = all)

SAMPLING_BLOCKED_CHATS

""

Comma-separated chat IDs/usernames to ignore

SAMPLING_ALLOWED_USERS

""

Comma-separated user IDs to allow (empty = all)

SAMPLING_BLOCKED_USERS

""

Comma-separated user IDs to ignore

SAMPLING_ADMIN_USERS

""

Comma-separated user IDs who can use admin commands

Rate Limiting

Variable

Default

Description

SAMPLING_RATE_LIMIT_USER

10

Max requests per user per minute

SAMPLING_RATE_LIMIT_CHAT

20

Max requests per chat per minute

Message Type Support

Variable

Default

Description

SAMPLING_ENABLE_TEXT

true

Enable text messages

SAMPLING_ENABLE_PHOTO

true

Enable photo messages

SAMPLING_ENABLE_DOCUMENT

true

Enable document uploads

SAMPLING_ENABLE_VOICE

true

Enable voice messages

SAMPLING_ENABLE_VIDEO

true

Enable video messages

SAMPLING_ENABLE_STICKER

true

Enable sticker messages

SAMPLING_ENABLE_LOCATION

true

Enable location sharing

SAMPLING_ENABLE_CONTACT

true

Enable contact sharing

SAMPLING_ENABLE_POLL

true

Enable poll messages

Content Filtering

Variable

Default

Description

SAMPLING_MIN_MESSAGE_LENGTH

1

Minimum message length

SAMPLING_MAX_MESSAGE_LENGTH

1000

Maximum message length

SAMPLING_KEYWORD_TRIGGERS

""

Only respond to messages with these keywords

SAMPLING_IGNORE_COMMANDS

true

Ignore messages starting with /

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

Parameter

Type

Required

Description

fromChatId

string

number

Yes

toChatId

string

number

Yes

messageId

number

Yes

ID of the message to forward

disableNotification

boolean

Forward message silently

GET_CHANNEL_INFO

Get information about a Telegram channel or chat

Parameter

Type

Required

Description

channelId

string

number

Yes

GET_CHANNEL_MEMBERS

Get a list of channel administrators and members

Parameter

Type

Required

Default

Description

channelId

string

number

Yes

limit

number

10

Maximum number of members to retrieve (1-50)

PIN_MESSAGE

Pin a message in a Telegram chat or channel

Parameter

Type

Required

Description

chatId

string

number

Yes

messageId

number

Yes

ID of the message to pin

disableNotification

boolean

Pin message silently

SEND_MESSAGE

Send a message to a Telegram chat or channel

Parameter

Type

Required

Description

chatId

string

number

Yes

text

string

Yes

The message text to send

topicId

number

The topic ID for forum channels (optional)

parseMode

string

Optional parse mode: Markdown, MarkdownV2, HTML, or Text (plain text)

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

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

MIT

Available Tools

5 tools
FORWARD_MESSAGEC

Forward a message from one chat to another

Inputs: toChatId (required), messageId (required), fromChatId (required), disableNotification.

GET_CHANNEL_INFOB

Get information about a Telegram channel or chat

Inputs: channelId (required).

GET_CHANNEL_MEMBERSC

Get a list of channel administrators and members

Inputs: channelId (required), limit.

PIN_MESSAGEB

Pin a message in a Telegram chat or channel

Inputs: chatId (required), messageId (required), disableNotification.

SEND_MESSAGEB

Send a message to a Telegram chat or channel

Inputs: text (required), chatId (required), topicId, parseMode.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: sending, forwarding, pinning messages, getting channel info, and listing members. No overlap or ambiguity.

    Naming Consistency5/5

    All tool names follow the same UPPER_SNAKE_CASE verb_noun pattern, e.g., SEND_MESSAGE, GET_CHANNEL_INFO. Highly consistent.

    Tool Count5/5

    Five tools is perfectly scoped for a Telegram MCP server, covering essential messaging and channel operations without excess.

    Completeness4/5

    Covers core operations (send, forward, pin, info, members) but is missing update/delete message capabilities, which are reasonable gaps for a focused tool set.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that enables interaction with Telegram to send, read, and search messages across chats and dialogs. It supports waiting for incoming messages and retrieving conversation history through natural language commands.
      31 npm
      3
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that wraps the Telegram Bot API into semantic tools for LLM agents, supporting multi-bot management for sending and receiving messages. It enables agents to send text, photos, and documents, as well as fetch recent updates from multiple configured Telegram bots.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server that enables Telegram bot interaction via Telegraf, providing tools for sending, replying, reacting, editing, deleting, forwarding messages, and receiving Telegram events over an optional notification channel.
      41 npm
      4
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server enabling AI agents to interact with users via Telegram, supporting message and image sending, inline quick replies, and waiting for user responses.
      5 npm
      MIT