telegram-mcp-server
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
telegram-mcp-server
A Telegram MCP server via Telethon — persistent client, flood-safe, 9 grouped tools.
Zero API keys in code. Session files stored locally. Works with user accounts (2FA) and bots.
1. Install
git clone <this-repo> telegram-mcp-server
cd telegram-mcp-server
python -m venv .venv
# Windows:
.venv\Scripts\activate
# macOS/Linux:
source .venv/bin/activate
pip install -e .Get your API credentials
Go to my.telegram.org
Log in with your phone number
Create an app → get API ID and API Hash
One-time auth
# User account (with 2FA support)
export TG_API_ID=12345
export TG_API_HASH="your_hash_here"
telegram-mcp-server --auth --phone +33612345678
# Or via MCP tool: tg_session(action="auth", api_id=12345, api_hash="...", phone="+33612345678")Related MCP server: telegram-mcp
2. Register in your MCP client
Claude Desktop / OpenCode
{
"mcpServers": {
"telegram": {
"command": "telegram-mcp-server",
"env": {
"TG_API_ID": "12345",
"TG_API_HASH": "your_hash_here"
}
}
}
}If not on PATH:
{
"mcpServers": {
"telegram": {
"command": "/path/to/.venv/bin/python",
"args": ["-m", "telegram_mcp_server"],
"env": {
"TG_API_ID": "12345",
"TG_API_HASH": "your_hash_here"
}
}
}
}Docker
docker build -t telegram-mcp .
docker run -i --rm \
-v ~/.telegram-mcp/sessions:/root/.telegram-mcp/sessions \
-e TG_API_ID=12345 \
-e TG_API_HASH="your_hash" \
telegram-mcp3. Tool catalog (9 tools, 8 actions)
tg_session — Session management
action | Required args | Description |
|
| Authenticate (2FA supported) |
| — | Check login status |
| — | Delete session |
tg_message — Send, forward, delete, reply
action | Required args | Description |
|
| Send a message |
|
| Forward a message |
|
| Delete a message |
|
| Reply to a message |
tg_chat — Chat operations
action | Required args | Description |
| — | List recent chats |
|
| Get chat info |
|
| List chat members |
|
| Leave a chat |
tg_search — Search
action | Required args | Description |
|
| Search messages (optionally in |
|
| Search contacts/users |
|
| Search channels |
tg_history — Chat history
action | Required args | Description |
|
| Get message history |
|
| Get media-only history |
|
| Get file-only history |
tg_user — User operations
action | Required args | Description |
| — | Get your own info |
|
| Get user info |
|
| Block a user |
|
| Unblock a user |
tg_media — Send media
action | Required args | Description |
|
| Send a photo |
|
| Send a video |
|
| Send a document |
|
| Send a voice note |
tg_channel — Channel management
action | Required args | Description |
|
| Create a supergroup/channel |
|
| Join a channel |
|
| Leave a channel |
|
| Get channel info |
tg_draft — Draft messages
action | Required args | Description |
|
| Save a draft |
| — | List all drafts |
|
| Delete a draft |
4. Environment variables
Variable | Default | Description |
|
| Telegram API ID (from my.telegram.org) |
|
| Telegram API Hash |
|
| Session files location |
5. Safety
Rate limiter: Send actions capped at 5/min. Read actions unlimited.
FloodWaitError auto-retry: Waits the required time (capped at 5 min).
Session files: Local only, never committed to git.
2FA support: Full support for accounts with two-factor auth.
6. MCP resources
tg://version— Server versiontg://session/status— Login state
License
MIT
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Read chats and members; send, edit and delete messages with a bot in Telegram.
Telegram: FASTEST real time Telegram API. Retrieve channel's info and messages in milliseconds..
Multi-tenant Telegram gateway for AI agents — HTTP+stdio, 8 tools, MTProto User API
Telegram bots in one click, emoji and sticker packs, and search across Telegram channels and apps.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceConnects AI agents to Telegram via the official TDLib library, enabling tools like getting user info, listing dialogs, and searching messages.-
- AlicenseNot gradedqualityDmaintenanceEnables interaction with Telegram Bot API for sending messages, photos, editing messages, answering callbacks, and fetching updates.MIT
- AlicenseNot gradedqualityCmaintenanceEnables sending Telegram messages, photos, and documents, and retrieving bot information through the Telegram Bot API.334 npm1MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to interact with a user's Telegram account: list chats, read history, search, and send messages through Telegram's MTProto API.2MIT