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:
- Ask for your Telegram API credentials (from my.telegram.org/apps)
- Log in to Telegram
- Verify the bot is reachable
- 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 │
└─────────────┘
- Authenticate — Log in with your Telegram account (phone number)
- Discover — Crawl the bot:
/start,/help, buttons, full state graph via DFS - Expose — Every action becomes an MCP tool
- 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 setupwrites 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_IDTG_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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.