Telegram MCP Server

An MCP server that lets Claude (or any MCP client) control your personal Telegram account via the MTProto API (Telethon) — not a bot.

Send/read messages, media, search, reactions, scheduled messages, and full group/channel administration — all from your AI assistant, with built-in safety guards.

🇺🇿 O'zbekcha qo'llanma: README.uz.md

---

⚠️ Security & responsible use

• This server has full access to your account. Your .session file and api_hash act like a login — never share them or commit them to git (.gitignore already excludes them).
• Telegram limits automation. Bulk/spam messages can get your account limited or banned. Use responsibly, on your own account.
• Each user runs this with their own API credentials. There is no shared hosted service.

Built-in safety guards

Env var	Effect
TELEGRAM_READONLY=1	Disables every write/modify tool — read-only mode
TELEGRAM_ALLOWED_PEERS=@chan,123,me	Messages can only be sent to these peers
TELEGRAM_MAX_FLOODWAIT=60	Auto-wait up to N seconds on Telegram FloodWait, then retry

Destructive tools (delete_message, remove_participant, leave_chat) require an explicit confirm=true argument. FloodWait errors are caught and retried automatically.

Features (26 tools)

Messaging: send_message, read_messages, search_messages, reply_message, edit_message, forward_message, delete_message, pin_message, unpin_message, react, schedule_message, mark_read

Media: send_file (photo/document/video/voice), download_media

Discovery: get_me, list_dialogs, list_contacts, resolve_entity

Groups & channels: send_to_channel, create_group, get_participants, add_participants, remove_participant, promote_admin, join_chat, leave_chat

peer accepts an @username, phone number, chat ID, or "me" (Saved Messages).

---

Setup

1. Get API credentials

Go to my.telegram.org → API development tools → create an app. You'll get an api_id (number) and api_hash (string).

2. Install

git clone https://github.com/Muhammadyunusxon/telegram-mcp.git
cd telegram-mcp
pip3 install -r requirements.txt

3. Configure

cp .env.example .env

Edit .env and fill in TELEGRAM_API_ID and TELEGRAM_API_HASH.

4. Log in (once)

python3 login.py

Enter your phone (international format, e.g. +1555...), the code Telegram sends, and your 2FA password if enabled. This creates a telegram_mcp.session file so you won't need to log in again.

5. Connect to Claude Desktop

Edit your claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "telegram": {
      "command": "python3",
      "args": ["/absolute/path/to/telegram-mcp/server.py"]
    }
  }
}

The server reads credentials from .env automatically. Fully quit and reopen Claude Desktop, then look for the telegram tools.

Try it

• "Send 'hello' to my Saved Messages"
• "Send the file ~/report.pdf to @someone with caption 'draft'"
• "React 🔥 to message 1234 in @mychat"
• "Schedule 'Good morning' to @friend at 2026-07-21T06:00"

Knowledge base (answer from your own Q&A)

Store your own answers and let Claude reply from them instead of guessing. Answers live in knowledge.json (seeded from knowledge.example.json):

{ "entries": [ { "id": 1, "q": "What are your hours?", "a": "Mon–Fri 9–18.", "tags": ["hours"] } ] }

Three tools power it, using hybrid search (keyword + fuzzy, with optional semantic embeddings):

• answer_from_kb(question) — returns the best-matching entries; Claude writes the final reply from them (and won't fabricate if nothing matches).
• kb_add(question, answer, tags) — grow the base straight from chat.
• kb_list() — show everything stored.

Enable smarter semantic matching by installing fastembed and setting TELEGRAM_KB_SEMANTIC=1. Your knowledge.json is git-ignored so private answers never get pushed.

Realtime auto-responder (optional)

autoresponder.py is a long-running script that watches incoming Telegram messages and auto-replies from your knowledge base — phrased naturally by the Claude API. It runs independently of the MCP server.

Safety is built in: it only replies in allowlisted chats, only when the KB has a confident match (otherwise it stays silent), never replies to bots or itself, and rate-limits per chat.

pip install anthropic          # for AI phrasing (optional)

# Dry-run (no Telegram/API needed) — just checks KB gating:
python3 autoresponder.py --test "can I pay with card?"

# Live:
AUTORESPONDER_CHATS="@my_customers,123456789" \
ANTHROPIC_API_KEY="sk-ant-..." \
python3 autoresponder.py

Environment: AUTORESPONDER_CHATS (required allowlist), ANTHROPIC_API_KEY (optional — without it, the raw KB answer is sent verbatim), AUTORESPONDER_MODEL, AUTORESPONDER_MIN_SCORE (default 0.35), AUTORESPONDER_COOLDOWN. Keep it running 24/7 with nohup, screen, tmux, or a launchd/systemd service.

Install as a Claude Desktop Extension (.mcpb)

This repo ships a Desktop Extension bundle so it can be installed in one click and submitted to the Anthropic Connectors Directory.

• manifest.json — MCPB manifest (all tools annotated with readOnlyHint / destructiveHint; api_id / api_hash collected as sensitive user config).
• Download the .mcpb from Releases and open it with Claude Desktop, or build it yourself:

pip install -r requirements.txt --target lib   # vendor deps into the bundle
npx @anthropic-ai/mcpb pack . telegram-mcp.mcpb

One-time login: because this uses your Telegram account (MTProto), you must create the session once by running python login.py locally before the extension can connect. See PRIVACY.md for how your data is handled.

Development

pip install pytest
pytest -q

CI runs on Python 3.10–3.12 via GitHub Actions. A Dockerfile, pyproject.toml (build with python -m build), server.json (MCP registry), and smithery.yaml are included.

License

MIT