Skip to main content
Glama
Sign In
Telegram Account MCP

Telegram Account MCP

by Vlislavn
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Telegram account MCP

Local Telegram user-account MCP for Codex CLI and Claude Code. QR login is the default; no bot or web server.

QR replaces phone/code login—not API credentials. This user-account MCP cannot work without api_id and api_hash; a bot token is not a substitute for access to your personal chats. Get the credentials once (Telegram's instructions):

  1. Sign in at my.telegram.org with the phone number of your Telegram account and the code Telegram sends you.

  2. Open API development tools and create an application (fill in the required title, short name and other fields).

  3. Copy its numeric api_id and api_hash into your private .env as TELEGRAM_API_ID and TELEGRAM_API_HASH. Never paste them into an agent chat.

1. Sign in with QR

Requires Python 3.11+ and uv.

git clone https://github.com/Vlislavn/telegram-account-mcp.git
cd telegram-account-mcp
uv sync --locked --no-dev
cp .env.example .env
chmod 600 .env

After filling in .env, run uv run --no-sync telegram-account-mcp login.

On your phone: Telegram → Settings → Devices → Link Desktop Device → scan the terminal QR. Expired QR codes refresh automatically; enter your 2FA password if asked. The session is saved privately outside the repo at ~/.local/share/telegram-account-mcp/session.session. If QR is unavailable, use uv run --no-sync telegram-account-mcp login --phone instead.

Related MCP server: tgx

2. Connect one agent

Use your absolute checkout path and choose one command:

codex mcp add telegram -- uv --directory "/absolute/path/to/telegram-account-mcp" run --no-sync telegram-account-mcp serve
# or, from the Claude Code project where you want access:
claude mcp add --scope local telegram -- uv --directory "/absolute/path/to/telegram-account-mcp" run --no-sync telegram-account-mcp serve

Restart the agent; check codex mcp list or claude mcp list. No extra agent instructions are needed.

Tools: per-chat text history (by ID or @username), conversations by date (up to 31 days), outgoing messages by date. Sending text/replies is off by default. To expose it, set TELEGRAM_ENABLE_SEND=1 in .env and restart the agent; configure its per-call approval before sending. An uncertain send (status=unknown) must be checked in Telegram before retrying. Optional TELEGRAM_ALLOWED_CHAT_IDS restricts every tool to numeric chat IDs; unset means all accessible chats.

Privacy: never publish .env or .session. MCP message text can reach the agent's model provider. Two agents should not use one session simultaneously. QR/phone login has offline tests, but a real login still requires the owner to scan/confirm; it has not been verified with a live account.

Run offline tests: uv sync --locked && uv run pytest -q. Changes · MIT license.

Available Tools

3 tools
get_sent_messagesC
Read-only

Read outgoing text messages on an ISO date.

Inputs: date (required). Returns: result

telegram_get_chat_historyB
Read-only

Read newest-first text history by numeric ID or @username.

Inputs: chat_id (required), limit, before_msg_id. Returns: object

telegram_get_conversationsC
Read-only

Read text conversations on one date or an inclusive date range.

Inputs: date, end_date, chat_types, start_date, +3 more. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    B3.1/5.0

    Scored across 3 tools

    Disambiguation3/5

    get_conversations and get_chat_history both retrieve message history, one by date and the other by chat ID or username, so their boundaries overlap. get_sent_messages is more distinct as outgoing-only, but the overall set still has moderate ambiguity in read operations.

    Naming Consistency4/5

    All tool names use snake_case with a get_ verb, which is readable and mostly consistent. However, two tools are prefixed with telegram_ while get_sent_messages is not, creating a minor deviation.

    Tool Count4/5

    Three tools is a small but plausible set for a read-only Telegram message retrieval server. Each tool covers a distinct retrieval angle, though it is somewhat thin if the server's scope is broader account management.

    Completeness3/5

    The surface covers reading conversations, sent messages, and chat history, but lacks message search, media retrieval, contact/chat listing, and any send or write operations. These are notable gaps if the server is meant to represent a Telegram account comprehensively.

    Resources

    Related MCP Connectors

    Related MCP Servers

    • telegram-mcp

      Shaan-alpha
      A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to interact with a user's Telegram account: list chats, read history, search, and send messages through Telegram's MTProto API.
      2
      MIT

    • tgx

      mal4i6ka
      A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to operate a Telegram account through the same commands as the terminal client: messaging, chat management, voice transcription, calls, stickers, and privacy settings.
      1
      MIT

    • telegram-plugin

      kartollikaa
      A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI coding agents to read your own Telegram account via MTProto, including listing chats, searching and reading message history, resolving chats, and downloading attachments, with sending available only when explicitly enabled.
      MIT

    • tg-account-mcp

      Mesteriis
      A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to work with Telegram through explicitly selected user accounts and bots, supporting search, reading, sending, and message management with consent-based access.
      40 PyPI
      1
      Apache 2.0