Enables interaction with Telegram bots via the MTProto protocol, providing tools to send messages, wait for bot replies, and retrieve message history.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@telegram-mcpask @BotFather to list my bots"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
telegram-mcp
A minimal MCP server for Telegram bot interaction via MTProto — intentionally simple, easy to read, and easy to extend.
Looking for a full-featured Telegram MCP server? Check out chigwell/telegram-mcp — 60+ tools covering messaging, groups, contacts, media, admin, and more.
This project takes a different approach: two tools, ~150 lines of server code, zero complexity. It's a clean starting point for anyone who wants to understand how MCP servers work with Telegram, or who only needs basic bot messaging without the overhead of a full client.
Why this exists
Learning reference — Read the entire server in 5 minutes
Fork-friendly — Add exactly the tools you need, nothing you don't
Minimal dependencies — Just Telethon, MCP SDK, and python-dotenv
Tools
Tool | Description |
| Send a message to a Telegram bot and wait for its reply |
| Get message history with a Telegram bot |
Setup
1. Get Telegram API credentials
Log in with your phone number
Create a new application (any name/description)
Copy the API ID and API Hash
2. Install and authenticate
3. Configure your MCP client
Claude Code
Add to ~/.claude/settings.json:
Claude Desktop
Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):
Local development
If you've cloned the repo:
Configuration
Environment variable | Required | Default | Description |
| Yes | — | Your Telegram API ID |
| Yes | — | Your Telegram API hash |
| Auth only | — | Phone number for authentication |
| No | Auto-detect | Path to .env file |
| No | Working directory | Directory for session file |
How it works
This server uses the Model Context Protocol to expose Telegram interaction as tools that any MCP-compatible AI client can use. Under the hood, it:
Connects to Telegram via MTProto using your pre-authenticated session
Sends messages to bots as your user account
Polls for replies and returns structured JSON responses
Disconnects cleanly after each operation
Security notes
Your session file (
telegram_user.session) contains auth tokens — never commit itThe
.gitignoreexcludes session files by defaultAPI credentials should be passed via environment variables, not hardcoded
This tool acts as YOUR Telegram account — treat it accordingly
Development
Requirements
Python 3.10+
uv (recommended) or pip
License
MIT