Getting Started¶
Everything needed to get mcp-tg running against a Telegram account, in the order you need it.
This is a user account client over MTProto, not a bot — so it authenticates as you, with your phone number and 2FA, and the stored session is a bearer credential with full account access. That shapes the whole section: install, configure, log in once, and keep the session where it belongs.
Sections¶
-
Installation
Homebrew, apt, container, or a signed release binary — and how to register the server with an MCP client.
-
Agent Setup
A page written for your AI agent — hand it over and the agent walks you through the whole setup.
-
Configuration
Every environment variable and command-line flag, with its default.
-
Authentication
The
mcp-tg loginflow, where the session is stored, and how to recover a revoked one.
The short version¶
Get an app id and hash from my.telegram.org — the public builds carry no credentials — then:
brew install lexfrei/tap/mcp-tg
claude mcp add mcp-tg --env TELEGRAM_APP_ID=12345 --env TELEGRAM_APP_HASH=your_app_hash -- mcp-tg
On Debian or Ubuntu, sudo apt install mcp-tg from apt.lexfrei.dev does the same job and brings a systemd user unit with it — the full commands are in Installation.
On the first tool call that needs the account, the server asks for the phone and login code right in the client, and the session lands in the OS keychain (see Authentication).
Running many agent sessions or several MCP clients? Run one shared HTTP daemon instead of a process each — see Installation.