mcp-telegram

MCP server that wraps the Telegram Bot API as semantic tools for LLM agents — with multi-bot support for managing multiple agent conversations.

Works with Claude Code, Codex, Claude Desktop, Cursor, VS Code, Windsurf, and any MCP-compatible client.

Prerequisites

• Node.js 18+

• One or more Telegram bot tokens (create via @BotFather)

• Your Telegram chat ID

Multi-bot convention: Each TELEGRAM_BOT_<NAME> env var registers a bot. The <NAME> becomes the bot identifier used in tools (e.g., TELEGRAM_BOT_VENDAS → bot: "vendas").

Installation

Claude Code

claude mcp add telegram \
  -s local \
  -e TELEGRAM_BOT_VENDAS=your-token \
  -e TELEGRAM_CHAT_ID=your-chat-id \
  -- npx -y github:pauloFroes/mcp-telegram

Codex

Add to your codex.toml:

[mcp.telegram]
transport = "stdio"
command = "npx"
args = ["-y", "github:pauloFroes/mcp-telegram"]

[mcp.telegram.env]
TELEGRAM_BOT_VENDAS = "your-token"
TELEGRAM_CHAT_ID = "your-chat-id"

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "telegram": {
      "command": "npx",
      "args": ["-y", "github:pauloFroes/mcp-telegram"],
      "env": {
        "TELEGRAM_BOT_VENDAS": "your-token",
        "TELEGRAM_CHAT_ID": "your-chat-id"
      }
    }
  }
}

Cursor

Add to your .cursor/mcp.json:

{
  "mcpServers": {
    "telegram": {
      "command": "npx",
      "args": ["-y", "github:pauloFroes/mcp-telegram"],
      "env": {
        "TELEGRAM_BOT_VENDAS": "your-token",
        "TELEGRAM_CHAT_ID": "your-chat-id"
      }
    }
  }
}

VS Code

Add to your .vscode/mcp.json:

{
  "servers": {
    "telegram": {
      "command": "npx",
      "args": ["-y", "github:pauloFroes/mcp-telegram"],
      "env": {
        "TELEGRAM_BOT_VENDAS": "your-token",
        "TELEGRAM_CHAT_ID": "your-chat-id"
      }
    }
  }
}

Windsurf

Add to your ~/.windsurf/mcp.json:

{
  "mcpServers": {
    "telegram": {
      "command": "npx",
      "args": ["-y", "github:pauloFroes/mcp-telegram"],
      "env": {
        "TELEGRAM_BOT_VENDAS": "your-token",
        "TELEGRAM_CHAT_ID": "your-chat-id"
      }
    }
  }
}

Available Tools

Messaging

Updates & Management

Use Cases & Examples

• "Send today's sales summary via the vendas bot" — Collects data from other MCPs, formats a report, sends via send_message with bot: "vendas"

• "Alert me on Telegram if ad spend exceeds R$500" — Checks Meta Ads data, sends alert via send_message with bot: "ads"

• "Check if Paulo replied to the last notification" — Calls get_updates on the relevant bot to read recent messages

• "Send this chart to my Telegram" — Uses send_photo with the image URL

Authentication

Bot tokens are passed in the URL path per Telegram Bot API convention. No OAuth flow required — each bot token is self-contained.

License

MIT