Skip to main content

tgbot2mcp — Turn any Telegram bot into an MCP server

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

PyPI GitHub Python 3.11+ License: MIT


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 (recommended — no install needed)
uvx tgbot2mcp setup @SomeBot
uvx tgbot2mcp serve @SomeBot

Requires uv.

pipx (permanent install)
pipx install tgbot2mcp
tgbot2mcp setup @SomeBot
Docker (HTTP/self-hosted)
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
From source (development)
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)

Tool What it does
send Send text or /command and get the response
click Click an inline or reply-keyboard button
read Read recent messages from the conversation
wait Wait for a delayed bot response
reset Reset conversation state
discover List all auto-discovered commands and buttons

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

Command Description
tgbot2mcp setup @Bot Full onboarding wizard (credentials + login + MCP config)
tgbot2mcp login Telegram authentication only
tgbot2mcp serve @Bot Start MCP server (stdio or HTTP)
tgbot2mcp inspect @Bot Show discovered bot capabilities
tgbot2mcp generate @Bot Generate standalone MCP server file

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

Do I need the bot's API token? No. tgbot2mcp uses your Telegram user session (MTProto). Works with any bot, even ones you don't own.
Is this safe? Session files (~/.tgbot2mcp/sessions/) give full access to your Telegram account. Never share them. Created with 0600 permissions.
Which AI clients work? Any MCP client: Claude Desktop, Cursor, Continue (VS Code), Cline, and others. Supports stdio and HTTP transports.
Can I use it with any bot? Yes. Any public Telegram bot that accepts messages will work.

Architecture

Component Source Role
Discovery BotFuzzer DFS crawling, state graph
Interaction TgTestKit Messages, buttons, edited messages
MCP MCP Python SDK Protocol implementation
Transport Telethon (MTProto) User-session Telegram access

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

Metadata

Release files for tgbot2mcp 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for tgbot2mcp 0.1.1
File Size Uploaded Provenance Actions
tgbot2mcp-0.1.1.tar.gz 88.3 kB Without provenance Details for tgbot2mcp-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for tgbot2mcp 0.1.1
File Interpreter ABI Platform Actions
tgbot2mcp-0.1.1-py3-none-any.whl Python 3 none any Details for tgbot2mcp-0.1.1-py3-none-any.whl

Total release size: 115.1 kB

Release files / tgbot2mcp-0.1.1.tar.gz

Download URL tgbot2mcp-0.1.1.tar.gz
Size 88.3 kB
Tags Source
SHA-256 checksum
How to use checksums
ca24e75da1330a642ea8e03c4f0d1587b1af94afffb9b840b09092acac5b38fe
BLAKE2b-256 checksum
How to use checksums
2f98509b985ac81c49203ccc9ed69ac3b778c832142d8fc091d6f970e53a29a1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.12.24 {"installer":{"name":"uv","version":"0.12.24","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / tgbot2mcp-0.1.1-py3-none-any.whl

Download URL tgbot2mcp-0.1.1-py3-none-any.whl
Size 26.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c38be1223684b324525b979649bae186473544cbeb253495c20f68cb462e942e
BLAKE2b-256 checksum
How to use checksums
481692a671f3da182bfcb98317c81062993fa3d21bbdc035e9812363c1679c7d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.12.24 {"installer":{"name":"uv","version":"0.12.24","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for tgbot2mcp 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page