Bridging Artificial Intelligence and Telegram.
Open-source Model Context Protocol (MCP) servers and modern terminal tools designed for AI coding agents and developers to build, test, and automate Telegram bots reliably.
Warning
Disclaimer: This organization and its repositories are independent open-source projects and are not affiliated with, authorized, maintained, sponsored, or endorsed by Telegram FZ-LLC, Telegram Messenger Inc., or any of their affiliates. "Telegram" is a registered trademark of its respective owners.
flowchart TD
subgraph Users ["Users & Agents"]
AI["🤖 AI Coding Agents\n(Cursor, Claude Desktop, Antigravity, Cline)"]
Human["👨💻 Human Developers\n(Terminal, Scripts & CI/CD)"]
end
subgraph Ecosystem ["Telegram MCP Ecosystem"]
Server["📦 telegram-mcp\n(MCP Server with 62 Tools)"]
CLI["⚡ telegram-mcp-cli\n(Command-Line Interface: tg-cli)"]
CoreGuard["🛡️ Shared Protections\n(Process Lock & Environment Mismatch Shield)"]
end
subgraph Telegram ["Telegram MTProto Network"]
TestDC["🧪 Test Server Cluster\n(DC 2 Sandbox / Zero-Risk)"]
ProdDC["🌐 Production Server Cluster\n(Live Network)"]
end
AI -->|MCP stdio Protocol| Server
Human -->|Shell Commands| CLI
Server --> CoreGuard
CLI --> CoreGuard
CoreGuard -->|TELEGRAM_TEST_MODE=true| TestDC
CoreGuard -->|TELEGRAM_TEST_MODE=false| ProdDC
| Repository | Primary Audience | Key Functionality | Quick Link |
|---|---|---|---|
telegram-mcp |
AI Coding Agents | 62 Model Context Protocol tools for autonomous bot testing, inline keyboard clicking, Mini App URL extraction, and media verification. | View Repo ➔ |
telegram-mcp-cli |
Human Developers | Modern terminal CLI (tg-cli) for manual testing, one-step session switching, chat history inspection, and scriptable automation. |
View Repo ➔ |
Connect your AI coding assistant (Antigravity CLI, Cursor, Claude Desktop, or Windsurf) to test bots autonomously:
git clone https://github.com/Telegram-mcp/telegram-mcp.git
cd telegram-mcp
pip install -r requirements.txtRegister server.py in your AI agent's MCP configuration:
{
"mcpServers": {
"telegram-bot": {
"command": "python3",
"args": ["/path/to/telegram-mcp/server.py"]
}
}
}Interact with bots and switch sessions directly from your shell:
pip install git+https://github.com/Telegram-mcp/telegram-mcp-cli.git
# Set active session directly from any .session file
tg-cli auth /path/to/my_account.session
# Inspect client health & DC alignment
tg-cli status
# Send commands and inspect bot replies
tg-cli command @BotFather /start- Exclusive Process Lock (
/tmp/telegram-mcp.lock): Telegram permanently revokes authorization keys if multiple connections use the exact same session simultaneously (AuthKeyDuplicatedError). Our tools enforce OS-level locking to keep your account safe. - Environment Mismatch Shield: Automatically inspects session Data Center IPs and prevents cross-environment connections between Test Server and Production clusters.
- Privacy by Default: Phone numbers and sensitive attributes are automatically masked in all outputs.
We welcome community contributions, bug reports, and feature requests! Check out our issues and pull requests across our repositories to get involved.
