@benjapieres/mcp-telegram-listener

Minimal MCP server that listens to Telegram messages and exposes them to AI agents. No third-party AI sampling, no magic — you control what happens with each message.

Setup

1. Create a Telegram bot

Talk to @BotFather and get your bot token.

2. Get your chat/group ID

Add the bot to your group, send a message, and check the logs — the chat ID will appear there. Group IDs are negative numbers (e.g. -1001234567890).

3. Configure your MCP client

Add this to your Claude Desktop or Claude Code MCP config:

{
  "mcpServers": {
    "telegram": {
      "command": "npx",
      "args": ["-y", "@benjapieres/mcp-telegram-listener"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "your_bot_token",
        "ALLOWED_CHAT_IDS": "-1001234567890,-1009876543210",
        "REQUIRE_MENTION": "false",
        "QUEUE_PATH": "/path/to/your/workspace/.meta/telegram-queue.json"
      }
    }
  }
}

Multiple bots (e.g. separate bots for different groups):

{
  "mcpServers": {
    "telegram-pm": {
      "command": "npx",
      "args": ["-y", "@benjapieres/mcp-telegram-listener"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "pm_bot_token",
        "ALLOWED_CHAT_IDS": "-1001234567890",
        "REQUIRE_MENTION": "false",
        "QUEUE_PATH": "/workspace/.meta/telegram-pm-queue.json"
      }
    },
    "telegram-leads": {
      "command": "npx",
      "args": ["-y", "@benjapieres/mcp-telegram-listener"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "leads_bot_token",
        "ALLOWED_CHAT_IDS": "-1009876543210",
        "REQUIRE_MENTION": "false",
        "QUEUE_PATH": "/workspace/.meta/telegram-leads-queue.json"
      }
    }
  }
}

Environment variables

| Variable | Required | Default | Description | |---|---|---|---| | TELEGRAM_BOT_TOKEN | Yes | — | Bot token from @BotFather | | ALLOWED_CHAT_IDS | No | (all) | Comma-separated chat/group IDs. Empty = accept all | | REQUIRE_MENTION | No | true | Set to false to receive all group messages without needing a bot mention | | QUEUE_PATH | No | ./telegram-queue.json | Absolute path for queue persistence across restarts |

Tools

| Tool | Description | |---|---| | get_messages | Returns pending messages and removes them from the queue | | peek_messages | Shows how many messages are queued without consuming them | | send_message | Sends a text message to a Telegram chat | | get_bot_info | Returns bot info and current configuration — useful to verify setup |

get_messages

Returns pending messages with sender info, username, chat ID, topic ID, reply_to ID, and timestamp.

| Parameter | Type | Required | Description | |---|---|---|---| | chat_id | string | No | Filter messages from a specific chat. Messages from other chats stay in queue. | | max_messages | number | No | Maximum messages to return (1–100). Default: all pending. | | format | string | No | "text" (default, human-readable) or "json" (structured array). |

peek_messages

Returns the current queue size without consuming messages. Also starts polling if not already running.

| Parameter | Type | Required | Description | |---|---|---|---| | chat_id | string | No | Count only messages from a specific chat. |

send_message

| Parameter | Type | Required | Description | |---|---|---|---| | text | string | Yes | Message text to send | | chat_id | string | No | Target chat ID. Defaults to first ALLOWED_CHAT_IDS | | topic_id | number | No | Topic/thread ID for forum supergroups (message_thread_id) | | reply_to_message_id | number | No | Reply to a specific message within the chat | | parse_mode | string | No | HTML, Markdown, or MarkdownV2 |

get_bot_info

No parameters. Returns bot id, username, name, and current config (allowed chats, require_mention, queue path).

How it works

Telegram  ←→  Bot (polling)  ←→  MCP server (stdio)  ←→  AI agent

• Polling starts lazily on the first get_messages or peek_messages call — not at initialization. This avoids token conflicts when multiple processes use the same bot.
• Incoming messages are stored in a FIFO queue (max 200)
• The agent reads messages on demand via get_messages
• Queue is persisted to disk and survives process restarts
• Everything runs locally — no external servers needed

License

MIT