Telegram Read-Only MCP Server
Provides read-only access to selected personal Telegram chats, enabling listing whitelisted chats and forum topics, reading recent messages from topics with message links, and searching messages within a chat.
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 → Claude Desktop: read-only MCP server
A small MCP server that gives Claude Desktop read-only access to selected chats of your personal Telegram account. Runs locally on your Mac via Telethon. There are no tools for sending messages — the server physically cannot write to Telegram.
Why: ask Claude "what was discussed in group X in the last 24 hours", "show me the forum topics", "find where we talked about Y" — and get an answer with links to the messages.
What's inside
File | Purpose |
| MCP server: |
| One-time authorization, creates the |
| Settings template — copy to |
| What to add to the Claude Desktop config |
| Dependencies with pinned versions (see "Pitfalls") |
| Excludes |
Related MCP server: Telegram MCP Server
Requirements
macOS (works on Linux too; config paths differ)
Python 3.10+ — the system Python on macOS is too old (see step 1)
Claude Desktop
A Telegram account with two-step verification enabled (strongly recommended)
Step-by-step setup
1. Fresh Python
brew install python@3.13
python3.13 --versionNo brew? Install it from brew.sh.
2. Telegram API keys
Go to my.telegram.org → API development tools.
Create an application (any name).
Note down
api_idandapi_hash.In Telegram: Settings → Privacy and Security → Two-Step Verification → enable if not already.
3. Folder and environment
git clone https://github.com/julijakvetna/telegram-readonly-mcp.git ~/tg-mcp
cd ~/tg-mcp
python3.13 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt4. The .env file
cp .env.example .env
open -e .envFill in:
TG_API_ID=12345
TG_API_HASH=your_hash
TG_ALLOWED_CHATS=Chat name 1,Chat name 2
TG_DEFAULT_CHAT=Chat name 1
TG_SESSION_NAME=telegramTG_ALLOWED_CHATS is a whitelist: the server sees only these dialogs. Use the exact titles as shown in your Telegram chat list; case-insensitive; comma-separated.
5. Authorization (once)
python login.pyIt asks for your phone number (international format, +1...), the code Telegram sends you, and your 2FA password. It should finish with Authorized as: … and the list of whitelisted chats. A telegram.session file appears — restrict its permissions:
chmod 600 telegram.session6. Test the server
python server.pyCorrect behavior: the command hangs and prints nothing (an MCP server waits for a connection). Stop with Ctrl+C. If you see a traceback instead, see "Pitfalls" below.
7. Connect to Claude Desktop
Claude Desktop → Settings → Developer → Edit Config. Add the block from claude_desktop_config.example.json, replacing your Mac username (find it with whoami):
{
"mcpServers": {
"telegram": {
"command": "/Users/YOUR_USER/tg-mcp/.venv/bin/python",
"args": ["/Users/YOUR_USER/tg-mcp/server.py"]
}
}
}Or do it with one terminal command (backs up the config and adds the block without touching other servers):
cd ~/tg-mcp && source .venv/bin/activate && python - <<'EOF'
import json, shutil
from pathlib import Path
p = Path.home() / "Library/Application Support/Claude/claude_desktop_config.json"
shutil.copy(p, p.with_suffix(".json.bak"))
cfg = json.loads(p.read_text())
here = Path.home() / "tg-mcp"
cfg.setdefault("mcpServers", {})["telegram"] = {
"command": str(here / ".venv/bin/python"),
"args": [str(here / "server.py")],
}
p.write_text(json.dumps(cfg, indent=2, ensure_ascii=False))
print("Servers:", ", ".join(cfg["mcpServers"]))
EOFFully restart Claude Desktop (⌘Q, then reopen — closing the window is not enough).
8. Test in Claude
New chat → the telegram connector should appear under the "+" menu. Ask:
show me the topics of and what was posted there in the last 24 hours
Tools
Tool | What it does |
| Whitelisted chats |
| Topics of a forum-style group: |
| Text messages from the last N hours, newest first, with |
| Full-text search inside a chat |
Empty chat = TG_DEFAULT_CHAT.
Pitfalls we hit (and fixes)
All of these are real errors from the first install, in the order they appeared.
pip version 21 / error installing mcp
The system Python on macOS is 3.8–3.9; the mcp package needs 3.10+. Fix: brew install python@3.13, recreate the venv (rm -rf .venv && python3.13 -m venv .venv).
ImportError: cannot import name 'GetForumTopicsRequest' from 'telethon.tl.functions.channels'
In recent Telethon the request moved to telethon.tl.functions.messages and the argument was renamed channel → peer. server.py already has a try/except that works with both versions. If you edit the code yourself, don't forget the closing } in **{_TOPICS_ARG: e}.
ModuleNotFoundError: No module named 'mcp.server.fastmcp' … This is mcp 2.x
pip install mcp installs 2.x, where FastMCP was renamed to MCPServer. The code targets 1.x, so requirements.txt pins mcp[cli]<2. If 2.x is already installed: pip install "mcp[cli]<2".
The connector doesn't show up in Claude Desktop
Either the config wasn't saved, Claude wasn't restarted with ⌘Q, or the server crashes on start. Run python server.py by hand — if there's a traceback, the cause is there.
The terminal complains about a line from the README
If you paste a block together with a # … comment, bash tries to execute it. Harmless, ignore.
Security — read this
<name>.session= full access to your Telegram account. Whoever gets the file can log in as you. Don't copy it, don't put it in cloud storage, don't commit it.chmod 600..envcontains yourapi_hash— also a secret..gitignorealready excludes both files; check before your firstgit push:git statusmust not show.envor*.session.The server only sees chats from
TG_ALLOWED_CHATSand has no write tools.Works while the Mac is on and Claude Desktop is open.
To revoke access: Telegram → Settings → Devices → terminate the app's session; then delete the
.sessionfile.
MIT © 2026 Judith Kvetna
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
Your Telegram, WhatsApp, Instagram, mail and calendar in Claude or ChatGPT. Never sends messages.
Your own WhatsApp in Claude and ChatGPT: read chats, draft replies, send messages you approve.
Search, read and reply to your Telegram Business chats, transcribed voice included.
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
- FlicenseNot gradedqualityFmaintenanceEnables Claude to interact with your Telegram account, including reading messages, searching conversations, and sending messages.-
- AlicenseAqualityDmaintenanceEnables reading and searching Telegram channel/group/DM messages from Claude Code using MTProto for full message history access.535 npmMIT
- FlicenseNot gradedqualityDmaintenanceEnables Claude to interact with Telegram, including listing chats, reading messages, sending messages, searching, and managing contacts.1-