@fre4x/telegram

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

Features

• Push Notifications: Sends incoming Telegram messages directly to the Claude Code session via notifications/push_event.
• 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. You can either provide these via a local .env file (for development) or directly inside your Claude Desktop / MCP client JSON configuration (recommended for production).

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.
• 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.

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

Development

npm run dev

Run the MCP Inspector:

npm run inspector