Telegram MCP Server
A Telethon MCP server: the agent reads and sends messages and manages chats, contacts and folders in your Telegram account
Install
git clone https://github.com/chigwell/telegram-mcp.git
cd telegram-mcp
uv sync
uv run session_string_generator.pyThe script prints a session string; store it like a password.
This is third-party code. Review the repository files before installing.
What it does
The server connects the agent to a Telegram user account via Telethon. The agent can search and read chats, send, schedule, edit and forward messages, create groups and channels, and manage admins, contacts, folders and drafts. Contacts can get the nicknames you actually use, and on a fuzzy match the server sends nothing and asks for confirmation. Voice messages can be transcribed via Groq or Telegram Premium's built-in transcription.
Who it is for. For people who handle work conversations in Telegram and want an agent to triage and answer them.
Good fit when
- You need a summary of unread chats
- You need to find an old message and reply to it
- You need to send a message out or create a group with members
Not a fit when
- You need a bot rather than access to a personal account
- You cannot hand an account session to a local process
Example request
Show unread messages from work chats and draft short replies, do not send anything without confirmationLimitations
Requires an API id and hash from my.telegram.org and a session string with full account access. TELEGRAM_EXPOSED_TOOLS=read-only hides write tools but does not restrict the session itself. Telegram may throttle many parallel sessions. The telegram-mcp package on PyPI belongs to another project, so install from the repository. Groq transcription needs a key and a foreign API, and Telegram access from Russia can be unstable.
How to disable. Remove the telegram-mcp block from the MCP config and end the session in Telegram under Settings, Devices.
MCP
- Transport
- stdio, http, sse
- Authentication
- API key
| Environment variables | |
|---|---|
| TELEGRAM_API_ID required, secret | App API id from my.telegram.org. |
| TELEGRAM_API_HASH required, secret | App API hash from my.telegram.org. |
| TELEGRAM_SESSION_STRING required, secret | Account session string from the generator. |
| TELEGRAM_EXPOSED_TOOLS | all, read-only or read-only+tool list. |
| GROQ_API_KEY secret | Groq key for voice transcription. |
Security check
- The session string grants full Telegram account access
- Can send and delete messages and change chat members and settings
README in short
The README describes tool groups for accounts, chats, messages, contacts, media, profile, folders and events. Installation is from a cloned repo via uv, and a script creates the session by QR code or phone number. The server speaks stdio, Streamable HTTP and SSE, with a shared HTTP process recommended for multiple clients. Multi-account setup, session pools, proxies, Docker and file path security are covered separately. Apache-2.0 licensed.
FAQ
Can I stop the agent from sending messages?
Yes, TELEGRAM_EXPOSED_TOOLS=read-only leaves reading only, and read-only+send_message adds specific write tools back.
Can I connect several accounts?
Yes, via TELEGRAM_SESSION_STRING_<label> variables. Write tools then require an account.
Related
A CLI for every Google Workspace API with JSON output and agent skills: Drive, Gmail, Calendar, Sheets and more
Local search over Markdown notes, docs and meeting transcripts: keywords, semantic search and reranking, with an MCP server
A task manager for AI-driven development: breaks a PRD into dependent tasks and guides the agent through them via MCP or CLI
Anthropic's official plugins for knowledge work roles: sales, support, product, marketing, legal, finance, data and enterprise search