Telegram MCP
Provides read-only access to Telegram chats, including listing chats, reading recent messages, and searching within a chat, using your own Telegram account credentials.
Click on "Deploy 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 MCP show me my unread messages from the family group chat"
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 — local read-only access for AI agents
The local MCP server gives Codex, Claude, and other MCP clients three tools:
Tool | Purpose |
| List chats and unread counts |
| Latest messages of the selected chat |
| Search text in the selected chat |
The server is read-only. There are no tools for sending, editing, or deleting messages in the code. The server runs locally via STDIO and intentionally does not provide network HTTP/SSE access.
Supported clients
ChatGPT/Codex Desktop;
Codex CLI and IDE extension;
Claude Code;
Claude Desktop;
any local MCP client with STDIO support.
The local server does not work directly in chatgpt.com, claude.ai, on a
phone, or on another computer: these environments cannot run a process on your
machine.
Related MCP server: telegram-mcp-server
What you'll need
Windows 10/11, macOS, or Linux;
Git;
at least one supported MCP client.
Installation for beginners
1. Open a terminal
macOS:
Command + Space→ typeTerminal→ Enter.Windows: Start menu → type
PowerShell→ open PowerShell.Linux: press
Ctrl + Alt + Tor open the Terminal app.
2. Download the project
macOS/Linux:
git clone https://github.com/iamalexzatcepin/telegram-mcp-template.git ~/telegram-mcp
cd ~/telegram-mcpWindows PowerShell:
git clone https://github.com/iamalexzatcepin/telegram-mcp-template.git "$env:USERPROFILE\telegram-mcp"
cd "$env:USERPROFILE\telegram-mcp"If GitHub reports that the repository is not found, your account does not yet have access to the private repository.
3. Get your Telegram API ID and API Hash
Open my.telegram.org.
Sign in with your phone number.
Open API development tools.
Create an app, e.g.
Local Telegram MCP.Save
api_idandapi_hash.
Do not send api_hash, the login code, or the cloud password to an AI chat.
Create a local .env.
macOS/Linux:
cp .env.example .env
nano .envSaving in Nano: Ctrl + O → Enter → Ctrl + X.
Windows PowerShell:
Copy-Item .env.example .env
notepad .envFill in the file locally:
TELEGRAM_API_ID=ваш_api_id
TELEGRAM_API_HASH=ваш_api_hash4. Install dependencies and sign in to Telegram
macOS/Linux:
bash setup.shWindows PowerShell:
powershell -ExecutionPolicy Bypass -File setup.ps1The script will find Python 3.10+ itself, create .venv, install dependencies,
and ask for your phone number, the code from Telegram, and, if enabled, the
cloud password. Enter them only in your own terminal.
Connecting to an agent
In all examples, use the absolute paths printed by the setup script. The
command is Python inside .venv, the argument is telegram_mcp_server.py.
Codex CLI and ChatGPT/Codex Desktop
macOS/Linux:
codex mcp add telegram -- "$HOME/telegram-mcp/.venv/bin/python" "$HOME/telegram-mcp/telegram_mcp_server.py"
codex mcp get telegramWindows PowerShell:
codex mcp add telegram -- "$env:USERPROFILE\telegram-mcp\.venv\Scripts\python.exe" "$env:USERPROFILE\telegram-mcp\telegram_mcp_server.py"
codex mcp get telegramIn ChatGPT/Codex Desktop you can also open Settings → MCP servers → Add server, select STDIO, and specify the same Command and Arguments. After saving,
click Restart. Local clients of the same Codex host share the
~/.codex/config.toml configuration.
Claude Code
macOS/Linux:
claude mcp add --transport stdio --scope user telegram -- "$HOME/telegram-mcp/.venv/bin/python" "$HOME/telegram-mcp/telegram_mcp_server.py"
claude mcp get telegramWindows PowerShell:
claude mcp add --transport stdio --scope user telegram -- "$env:USERPROFILE\telegram-mcp\.venv\Scripts\python.exe" "$env:USERPROFILE\telegram-mcp\telegram_mcp_server.py"
claude mcp get telegramStart a new Claude Code session and type /mcp. The user scope makes the
server available across different local projects of this user.
Claude Desktop
Open the Developer/MCP settings and add a local STDIO server. If your Claude Desktop version uses a JSON configuration, add the object while keeping the other servers:
{
"mcpServers": {
"telegram": {
"command": "/absolute/path/to/telegram-mcp/.venv/bin/python",
"args": ["/absolute/path/to/telegram-mcp/telegram_mcp_server.py"]
}
}
}Typical file locations:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.json;Windows:
%APPDATA%\Claude\claude_desktop_config.json.
Fully restart Claude Desktop and open a new chat.
Another STDIO MCP client
Use an equivalent configuration:
{
"mcpServers": {
"telegram": {
"command": "/absolute/path/to/.venv/bin/python",
"args": ["/absolute/path/to/telegram_mcp_server.py"]
}
}
}Final check
Ask the agent:
Use telegram
list_chatswith limit=10 and show the name, type, and number of unread messages.
Do not consider the installation complete until the agent has actually returned the list of your chats.
Multiple accounts
The server supports separate local sessions default, work, personal, and
others. Instructions are in docs/MULTI_ACCOUNT.md.
Instructions for AI agents
If Codex, Claude, or another agent is performing the installation, ask it to fully read docs/AGENT_SETUP.md and follow it step by step. This file contains security rules and branches for different OSes.
Security and limitations
.envandsessions/are excluded from Git;the
.sessionfile grants access to the account — do not copy or publish it;media files are not downloaded, only the
has_mediaflag is returned;requests to Telegram are executed on behalf of your account and obey Telegram's limits;
do not run two operations with the same
.sessionat the same time;do not expose this server to the internet.
More: SECURITY.md.
If something doesn't work
Development
.venv/bin/python -m unittest discover -s tests -vProject structure:
File | Purpose |
| Three read-only MCP tools, STDIO only |
| Loading settings and local Telethon sessions |
| Sign in and create a named session |
| Installation on macOS/Linux |
| Installation on Windows |
| Step-by-step protocol for AI agents |
| Connecting multiple accounts |
| Diagnosing common issues |
License
MIT — the project can be used, modified, and distributed with the copyright notice and the license text preserved.
Available Tools
14 toolsanalyze_chat_activityC
Compute deterministic activity statistics; the calling agent writes narrative analysis.
Inputs: chat (required), limit, account, topic_id.
get_message_contextC
Read one message and bounded surrounding context.
Inputs: chat (required), message_id (required), after, before, +1 more.
get_unreadA
Return unread messages grouped by chat without marking them read.
Inputs: account, limit_chats, limit_per_chat.
inspect_permissionsA
Show the active profile, allowed capabilities, and physically exposed tools.
Inputs: no named parameters.
list_chat_foldersC
List Telegram chat folders without changing their configuration.
Inputs: account.
list_chatsC
List chats, stable references, unread counts, and pinned state.
Inputs: limit, account.
list_folder_chatsC
List chats visible in one Telegram folder by its numeric folder id.
Inputs: folder_id (required), limit, account.
list_forum_topicsC
List topics in a Telegram forum chat, including unread state.
Inputs: chat (required), limit, query, account.
read_chatC
Read recent messages from a chat, returned oldest-first.
Inputs: chat (required), limit, account.
read_forum_topicB
Read recent messages from one forum topic without marking it read.
Inputs: chat (required), topic_id (required), limit, account.
search_chatC
Search message text within one chat.
Inputs: chat (required), query (required), limit, account.
search_forum_topicC
Search message text inside one forum topic.
Inputs: chat (required), query (required), topic_id (required), limit, +1 more.
search_globalC
Search message text across all dialogs.
Inputs: query (required), limit, account.
telegram_diagnosticsA
Inspect local runtime/config/storage state without returning secrets or messages.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Each tool targets a distinct scope or operation: search by chat/global/forum topic, list chats/folders/topics, read chat/topic/unread/context, plus analysis and diagnostics. Overlaps are minimal and descriptions clearly differentiate boundaries (e.g., read_chat vs read_forum_topic).
Most tools follow a consistent verb_noun snake_case pattern (search_chat, list_chats, get_unread). One outlier is telegram_diagnostics, which lacks a verb and slightly breaks the pattern, but overall naming is predictable.
14 tools is well-scoped for a read-only Telegram client surface, covering search, read, list, and diagnostic needs without redundant or excessive operations.
The read-only surface is quite complete for searching, reading, listing, and analyzing chats, including unread and forum topic support. Minor gaps remain in exposing detailed chat metadata (e.g., profile info) or any write operations, though the latter may be intentional.
Maintenance
Related MCP Connectors
Telegram bridge for your MCP-compatible agent. Bidirectional, no LLM in our stack.
Search your AI chat history (ChatGPT, Claude, Codex) from any MCP client. Remote, private, read-only
Read-only WhatsApp MCP for your AI agent: it reads the chats you choose. Try the public demo.
Your personal Telegram account for AI: read, search and sum up chats. QR login, no API key.
Related MCP Servers
- AlicenseAqualityBmaintenanceRead-only Telegram access for Claude and other MCP hosts. Provides tools to list chats, read recent messages, and download media from your own Telegram account without needing an api_id/api_hash.567 npmMIT
- AlicenseNot gradedqualityDmaintenanceA read-only MCP server that lets AI agents read personal Telegram chats from an allowlist of folders, with no send/edit/delete capability.MIT
- AlicenseNot gradedqualityDmaintenanceEnables reading Telegram chats and searching messages through natural language, connecting to MCP clients like Claude Code, Codex, and Cursor.26 npm1MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to interact with a personal Telegram account via MCP, offering tools for reading and searching chats, summarizing unread messages, sending and editing messages, handling files and voice transcripts, and managing groups and channels, with read-only mode by default.Apache 2.0