@fre4x/telegram

Telegram MCP server implementing Claude Code Channels for bidirectional communication and remote permission relay.

Features

• Push Notifications: Sends incoming Telegram messages to the connected MCP client via notifications/message (claude/channel protocol).
• Bidirectional Chat: Allows Claude to send messages to Telegram using the send_telegram_message tool.
• Security: Filters incoming messages based on an allowed user ID.
• Remote Control: (Planned) Approve or deny Claude's tool-use prompts from your mobile device.

Installation

npm install
npm run build

Configuration

This MCP server requires environment variables to secure its endpoints and access the Telegram API. Provide them in your Claude Desktop / MCP client JSON configuration. For local development, export the same variables in your shell (or set -a; source .env; set +a). The server does not load .env files itself.

Environment Variables

• TELEGRAM_BOT_TOKEN (Required): Your bot's API token. Obtain this by talking to @BotFather.
• ALLOWED_USER_ID (Required): The primary Telegram numeric user ID allowed to send messages to the bot in private chats and use commands. Obtain this via @userinfobot.
• TELEGRAM_STATE_PATH (Optional): Override the persisted chat-state file path. Leading ~ / ~/ is expanded by the server (not the shell).
• ENABLE_RECIPIENT_WHITELIST (Optional): Set to "true" to enforce a strict whitelist of users/groups the bot is allowed to message.
• ALLOWED_RECIPIENTS (Optional): A comma-separated list of Telegram numeric IDs (e.g., 1234567,-100987654) that Claude is permitted to message.
• TELEGRAM_EVENT_RELAY (Optional): Set to "0" to disable the shared getUpdates hub (@fre4x/event-relay). Default is on whenever a bot token is present (not mock). Multiple MCP processes then share one Bot API long-poll via a local hub (node … --relay-hub).

MCP Client Setup (Claude Desktop)

To use this server with Claude Desktop or any standard MCP client, add the following configuration to your claude_desktop_config.json (or equivalent MCP settings file).

For macOS: ~/Library/Application Support/Claude/claude_desktop_config.json For Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "telegram": {
      "command": "npx",
      "args": [
        "-y",
        "@fre4x/telegram"
      ],
      "env": {
        "TELEGRAM_BOT_TOKEN": "your_bot_token_here",
        "ALLOWED_USER_ID": "your_telegram_user_id_here",
        "ENABLE_RECIPIENT_WHITELIST": "true",
        "ALLOWED_RECIPIENTS": "123456789"
      }
    }
  }
}

Usage with Claude Code (Channels)

If you are using this plugin as a bidirectional Claude Code channel rather than a standard tool server:

claude --channels plugin:telegram --dangerously-load-development-channels

Mock Mode

Run without a real bot token (returns fixture data of identical shape):

MOCK=true npx @fre4x/telegram

Development

npm run dev       # tsx, no build
npm run build     # esbuild → dist/
npm test          # vitest unit tests (MOCK=true)
npm run inspector # MCP Inspector (MOCK=true)