tlgrm

An unofficial, feature-rich command-line client, MCP server, and webhook daemon for Telegram, built on Telethon.

Drive your personal Telegram account from the terminal — or from an AI assistant — and bridge incoming messages to an HTTP webhook in real time.

Unofficial app notice: tlgrm is an independent, unofficial client built on the Telegram API (via Telethon). It is not affiliated with, endorsed by, or sponsored by Telegram.

Features

• Personal account — acts as you (MTProto user account, not a bot): read history, list members, message anyone you can.

• Multi-account — log into several Telegram accounts, switch with -a/--account, and listen to all of them at once (like the mobile app).

• 30+ commands — send/reply/edit/delete, history & global search, reactions, forwarding, pin & mute, group management, scheduling, polls.

• Background server — an optional persistent process owns one hot connection per account; the CLI, MCP server, and webhook listener all route through it, so they run together with no database is locked conflict (and commands are near-instant).

• Real-time webhooks — forward incoming messages to an HTTP endpoint, per-account, optionally as a systemd service.

• Live filtering & permissions — per-account allow/block lists for both listening (filter listen) and writing (filter write), plus daily listening windows — all reconfigurable live.

• Scheduled messages — schedule send --at/--in, list, cancel (Telegram-native, fires even when offline).

• MCP server — tlgrm-mcp lets AI assistants drive Telegram (read-only by default), as a thin bridge to the server.

• Speech-to-text — auto-transcribe incoming voice notes (multilingual, GPU-aware, live-configurable via tlgrm stt), or transcribe any file with tlgrm transcribe.

• Clean JSON output — commands print JSON to stdout (logs go to stderr), so it pipes straight into jq and scripts.

→ See the full feature list — each one tagged by whether it needs the background server.

Related MCP server: tgmcp

Quick start

# 1. Get your API credentials from my.telegram.org → API development tools
export TG_API_ID=1234567
export TG_API_HASH=your_api_hash_here

# 2. Install — uv recommended (https://docs.astral.sh/uv/)
uv tool install "tlgrm[all]"      # everything (CLI + MCP + speech-to-text)
# uv tool install tlgrm           # CLI only
# uv tool install "tlgrm[mcp]"    # CLI + MCP server

# 3. Log in once
tlgrm login

# 4. Go
tlgrm chats --limit 10
tlgrm send --target @username --text "Hello!"
tlgrm chats | jq '.[].name'   # stdout is clean JSON; logs go to stderr

Prefer pip? Same package and extras: pip install tlgrm (or "tlgrm[mcp]", "tlgrm[stt]", "tlgrm[all]").

Telegram API credentials

tlgrm does not ship with API credentials — you must supply your own:

1. Go to my.telegram.org → API development tools.

2. Create an application (Platform: Desktop). The title must not contain the word "Telegram".

3. Copy the api_id (a number) and api_hash (a hex string).

4. Export them (add to your shell profile to persist):

export TG_API_ID=1234567
export TG_API_HASH=your_api_hash_here

See docs/03-configuration.md for all configuration options.

Commands (29)

Every command prints clean JSON to stdout — logs and progress go to stderr, so piping into jq works reliably.

Account & read

Write

Groups, scheduling & advanced

Webhook daemon

Full reference with all flags, output shapes, and examples: docs/02-commands.md.

MCP server

tlgrm ships a stdio MCP server (tlgrm-mcp). It is read-only by default; add --allow-write for write tools and --allow-write --allow-destructive for delete/leave/remove.

{
  "mcpServers": {
    "tlgrm": {
      "command": "uvx",
      "args": ["--from", "tlgrm[mcp]", "tlgrm-mcp", "--allow-write"],
      "env": { "TG_API_ID": "...", "TG_API_HASH": "..." }
    }
  }
}

The MCP server is a thin bridge to the background server: every tool call routes through the one owned connection (which enforces the permission tier and the write guard), and a server is auto-spawned if none is running. So the MCP server, the webhook daemon, and your CLI all run at once with no database is locked conflict — no --session juggling. Add --account NAME to act as a specific account (otherwise the server's default account is used). Requires a prior tlgrm login.

Full setup, permission tiers, and tool list: MCP guide.

Speech-to-text (optional)

Install the stt extra to auto-transcribe incoming voice notes in the webhook daemon, or to run tlgrm transcribe standalone (no login needed).

uv tool install "tlgrm[stt]"         # faster-whisper (default, recommended)
uv tool install "tlgrm[stt-whisper]" # original openai-whisper
uv tool install "tlgrm[stt-all]"     # all local backends
# (or pip install "tlgrm[stt]", etc.)

Cloud backends (openai, groq, deepgram, elevenlabs, google) need no extra package — just set the API key:

export OPENAI_API_KEY=sk-...   # auto-selects openai backend

Model tip: the default model is tiny (fast, lower accuracy). For good Arabic / multilingual accuracy, use a larger model:

export TG_STT_MODEL=large-v3-turbo   # recommended for Arabic

GPU: faster-whisper auto-detects NVIDIA GPUs (TG_STT_DEVICE=auto). CUDA 12 runtime required: pip install nvidia-cublas-cu12 nvidia-cudnn-cu12. Full backend reference: docs/03-configuration.md.

Security

• Your session file (~/.tlgrm/tg_session.session) grants full account access — keep it private (git-ignored by default).

• Enable Two-Step Verification on your Telegram account.

• The systemd unit file is written owner-only (0600).

Troubleshooting

Documentation

Contributing & License

Contributions welcome — see CONTRIBUTING.md. Released under the MIT License © 2026 Ali Alrabeei. tlgrm is unofficial and not affiliated with, endorsed by, or sponsored by Telegram.