Skip to main content
Glama
Sign In
telegram-user-mcp

telegram-user-mcp

by alexmakeev
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

telegram-user-mcp

Telegram user-account integration for MCP (Model Context Protocol), built on Telethon. Exposes Telegram operations (read/send messages, manage chats, etc.) to an MCP client over stdio or sse.

This is a containerized fork of chigwell/telegram-mcp.

Image

A public image is built by CI on every push to main and published to GHCR:

ghcr.io/alexmakeev/telegram-user-mcp:latest

Related MCP server: docker-telethon-plus

Configuration (runtime only)

All credentials are provided at runtime as environment variables — nothing is baked into the image. Obtain TELEGRAM_API_ID / TELEGRAM_API_HASH from https://my.telegram.org (API development tools).

Variable

Required

Description

TELEGRAM_API_ID

yes

Telegram API id

TELEGRAM_API_HASH

yes

Telegram API hash

TELEGRAM_SESSION_NAME

no

File-session name (default telegram_user)

TELEGRAM_SESSION_DIR

no

Directory for the file session (default /app/sessions)

TELEGRAM_SESSION_STRING

no

Portable string session (alternative to a file session)

TRANSPORT

no

stdio (default) or sse

LOG_LEVEL

no

Log level (default INFO)

Authenticating

You need either a session string or a session file for an authorized account:

  • String session: python session_string_generator.py (interactive), then set TELEGRAM_SESSION_STRING.

  • File session (QR login): python qr_auth.py, then mount the resulting sessions/ directory into the container.

A Telegram session grants full access to the account. Never commit session files or session strings. They are git-ignored here by default.

Run

docker run --rm \
  -e TELEGRAM_API_ID=... \
  -e TELEGRAM_API_HASH=... \
  -e TELEGRAM_SESSION_STRING=... \
  ghcr.io/alexmakeev/telegram-user-mcp:latest

License

Apache-2.0 (inherited from the upstream project). See pyproject.toml for authorship.

Tool Schema Changelog

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

Loading tool schema changelog…

    This server cannot be deployed

    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

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • telegram-mcp

      vkruglikov
      A
      license
      A
      quality
      D
      maintenance
      Enables use of a personal Telegram account within MCP clients for reading and sending messages, searching chats, and managing media, all running locally.
      16
      12 npm
      MIT

    • docker-telethon-plus

      psyb0t
      A
      license
      Not graded
      quality
      B
      maintenance
      Exposes a Telegram user account via MCP, enabling AI agents to send, read, and manage messages, chats, and media using full MTProto access through Telethon. It wraps Telethon behind a JSON HTTP API and MCP endpoint, allowing agents to interact with Telegram as the authenticated user.
      5
      GPL 2.0

    • telegram-mcp

      bssth
      A
      license
      B
      quality
      C
      maintenance
      Enables MCP clients to operate a Telegram account as a userbot, providing tools for reading and sending messages, searching chats and contacts, managing media, and performing other account actions via MTProto with a locally encrypted session.
      28
      MIT

    • Telegram MCP Server

      KiaroSama
      A
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP clients to drive a real Telegram account, exposing chats, messages, media, secret chats, admin rights, invite links, Mini Apps, and multi-account routing as callable tools.
      32
      GPL 3.0