English | Русский | 中文

tgbot2mcp

Turn any Telegram bot into a ready-to-use MCP server in one command.
No bot token required. Works with any existing Telegram bot through your user account.

What is this? An open-source Python adapter that connects to Telegram as a user (via MTProto), auto-discovers a target bot's capabilities, and exposes them as MCP tools — so AI agents (Claude, GPT, Gemini) can interact with any Telegram bot.

Quick Start

One command to set everything up:

uvx tgbot2mcp setup @SomeBot

This will:

1. Ask for your Telegram API credentials (from my.telegram.org/apps)
2. Log in to Telegram
3. Verify the bot is reachable
4. Auto-configure your MCP client (Claude Desktop / Cursor / VS Code)

Done. Your AI agent can now talk to the bot.

Installation

uvx tgbot2mcp setup @SomeBot
uvx tgbot2mcp serve @SomeBot

pipx install tgbot2mcp
tgbot2mcp setup @SomeBot

docker run --rm -it \
  -p 8080:8080 \
  -v tgbot2mcp-data:/data \
  -e TG_API_ID=123456 \
  -e TG_API_HASH=... \
  ghcr.io/megamen32/tgbot2mcp \
  serve @SomeBot --transport http --host 0.0.0.0 --port 8080

git clone https://github.com/megamen32/tgbot2mcp.git
cd tgbot2mcp
pip install -e ".[dev]"
tgbot2mcp setup @SomeBot

How It Works

┌─────────────┐     MTProto      ┌─────────────┐      MCP       ┌─────────────┐
│  Telegram    │ ───────────────▶ │  tgbot2mcp  │ ─────────────▶ │  AI Agent   │
│  Bot (@bot)  │ ◀─────────────── │             │ ◀───────────── │ (Claude etc)│
└─────────────┘   Bot responses   │  • Discover │   Tool calls   └─────────────┘
                                   │  • Interact │
                                   │  • Expose   │
                                   └─────────────┘

1. Authenticate — Log in with your Telegram account (phone number)
2. Discover — Crawl the bot: /start, /help, buttons, full state graph via DFS
3. Expose — Every action becomes an MCP tool
4. Interact — AI agents send messages, click buttons, navigate states

MCP Tools

Universal (always available)

Dynamic (auto-generated from bot discovery)

• cmd_{name} — one tool per slash command (cmd_start, cmd_help, etc.)
• btn_{label} — one tool per button found in bot responses

MCP Client Configuration

Claude Desktop

{
  "mcpServers": {
    "telegram-bot": {
      "command": "uvx",
      "args": ["tgbot2mcp", "serve", "@YourBot"],
      "env": {
        "TG_API_ID": "YOUR_API_ID",
        "TG_API_HASH": "YOUR_API_HASH"
      }
    }
  }
}

Tip: tgbot2mcp setup writes this config for you automatically.

Cursor / VS Code

Same format — saved to ~/.cursor/mcp.json or ~/.vscode/mcp.json by setup.

Commands

Serve options

# stdio (default — for Claude Desktop, Cursor)
tgbot2mcp serve @SomeBot

# HTTP transport (for remote/self-hosted)
tgbot2mcp serve @SomeBot --transport http --port 8080

# Skip discovery (universal tools only, faster startup)
tgbot2mcp serve @SomeBot --no-discover

Configuration

Config: ~/.tgbot2mcp/config.yaml

api_id: 12345
api_hash: "your_api_hash"
session_dir: ~/.tgbot2mcp/sessions
default_timeout: 20.0
discovery_max_depth: 5

Environment variables (override config):

• TG_API_ID / TELEGRAM_API_ID
• TG_API_HASH / TELEGRAM_API_HASH

FAQ

Architecture

License

MIT

🇷🇺 Русский

tgbot2mcp — превращает любого Telegram-бота в MCP-сервер одной командой.
Токен бота не нужен — работает через ваш аккаунт.

uvx tgbot2mcp setup @SomeBot

Мастер настройки сам запросит API-ключи, выполнит авторизацию, проверит бота и настроит MCP-клиент (Claude / Cursor / VS Code).

Ручной запуск:

uvx tgbot2mcp login
uvx tgbot2mcp serve @SomeBot

Нужен uv и API-ключи с my.telegram.org/apps.

🇨🇳 中文

tgbot2mcp — 一条命令将任何 Telegram 机器人变为 MCP 服务器。
无需机器人 Token，通过您的用户账户运行。

uvx tgbot2mcp setup @SomeBot

设置向导会自动请求 API 密钥、完成登录、验证机器人并配置 MCP 客户端（Claude / Cursor / VS Code）。

手动运行：

uvx tgbot2mcp login
uvx tgbot2mcp serve @SomeBot

需要 uv 和 my.telegram.org/apps 的 API 密钥。

_{Built with Telethon · MCP Python SDK · Inspired by BotFuzzer & TgTestKit}