Telegram MCP Server

A local Model Context Protocol server that gives an AI agent — Claude Code, Claude Desktop, or any MCP client — controlled access to your own Telegram account: list chats, read history, search, and send messages, through Telegram's MTProto API.

Built with Python + Telethon. Runs entirely on your machine; your login session never leaves it.

Why

Telegram's Bot API can't see your existing chats — a bot is a separate identity and only receives messages explicitly sent to it. To let an agent work with your real conversations you need the MTProto client API, authenticated as your user account. This project wraps that in a small, focused MCP server so any MCP-capable agent can read and act on your Telegram — without you writing glue code each time.

Features

• 6 tools covering the common read/write actions (see below)
• Local-only — credentials and session live in a git-ignored .env; nothing is sent anywhere except Telegram
• Standard MCP stdio server — works with Claude Code, Claude Desktop, or any MCP client
• One-time login — interactive script stores a reusable session string; no re-auth on every run
• Small and readable — ~150 lines of Python, easy to audit and extend

Tools

Tool	Description
get_me()	Return the connected account (sanity check)
list_chats(limit=20)	Your most recent conversations
get_history(chat, limit=30)	Recent messages from one chat
search_messages(chat, query, limit=30)	Search within one chat
search_all(query, limit=30)	Search across all your chats at once
send_message(chat, text)	Send a message as you

chat accepts a username (@name), numeric id, phone number, t.me link, or the chat's display name.

Quickstart

1. Install

git clone https://github.com/<you>/telegram-mcp.git
cd telegram-mcp
python -m venv .venv

# Windows
.venv\Scripts\pip install -r requirements.txt
# macOS / Linux
.venv/bin/pip install -r requirements.txt

2. Get API credentials

Go to my.telegram.org → API development tools → create an app → copy the api_id and api_hash.

3. Log in (one time)

# Windows
.venv\Scripts\python login.py
# macOS / Linux
.venv/bin/python login.py

Enter your api_id/api_hash, phone number (with country code), and the login code Telegram sends you (plus your 2FA password if set). This writes a reusable session to .env.

4. Register with your MCP client

Claude Code:

claude mcp add telegram --scope user -- "/abs/path/.venv/bin/python" "/abs/path/server.py"

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "telegram": {
      "command": "/abs/path/.venv/bin/python",
      "args": ["/abs/path/server.py"]
    }
  }
}

Restart your client and the telegram tools are available.

Example

You: Search all my Telegram chats for "invoice" and summarize what's outstanding.

The agent calls search_all("invoice"), which returns:

[
  {
    "id": 84213,
    "date": "2026-07-02T09:14:00+00:00",
    "chat": "Acme Billing",
    "from": "Acme Billing",
    "text": "Invoice #204 is due on the 10th."
  }
]

…and the agent summarizes from there.

How it works

login.py authenticates once via Telethon and saves a StringSession to .env. server.py builds a FastMCP stdio server, connects lazily on the first tool call, verifies the session is authorized, and maps each tool to a Telethon call (iter_dialogs, iter_messages, SearchGlobalRequest, send_message). Results are returned as plain JSON-serializable dicts.

Security

• Keep .env private. The SESSION_STRING is equivalent to being logged in as you. It is git-ignored — never commit it.
• Everything runs locally; the server talks only to Telegram's servers.
• Automating a user account is a Telegram ToS gray area. Reading your own account is generally fine; keep sending human-paced and avoid bulk/spam activity to stay clear of account limits.

Limitations

• No automated test suite yet — verified manually against a live account.
• search_messages searches a single chat; use search_all for a global search.
• Display-name resolution falls back to scanning your dialog list, so exact usernames/ids are faster and more reliable.

License

MIT