Skip to main content
Glama
alexmakeev

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.

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 issues

Resources

Related MCP Connectors

Related MCP Servers

  • telegram-mcp

    vkruglikov
    A
    license
    A
    quality
    B
    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
    3 npm
    MIT

  • docker-telethon-plus

    psyb0t
    A
    license
    Not graded
    quality
    A
    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.
    2
    Do What The F*ck You Want To Public

  • 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.
    1
    GPL 3.0