mcp-tg

MCP server for Telegram Client API (MTProto). Provides 80 tools, 4 resources, 3 prompts, and argument completions for comprehensive Telegram account management.

Uses gotd/td for MTProto protocol — this is a user account client, not a bot.

📖 Full documentation: mcp-tg.lexfrei.dev

Homebrew (macOS, Linux) — also installs a brew services unit for the shared HTTP daemon:

brew install lexfrei/tap/mcp-tg

APT (Debian, Ubuntu) — also ships a systemd user unit for the shared HTTP daemon:

curl --fail --silent --show-error --location https://apt.lexfrei.dev/lexfrei.asc \
  | sudo gpg --dearmor --output /usr/share/keyrings/lexfrei.gpg

sudo tee /etc/apt/sources.list.d/lexfrei.sources >/dev/null <<'EOF'
Types: deb
URIs: https://apt.lexfrei.dev
Suites: stable
Components: main
Signed-By: /usr/share/keyrings/lexfrei.gpg
EOF

sudo apt update && sudo apt install mcp-tg

Container:

docker pull ghcr.io/lexfrei/mcp-tg:latest

Binary: darwin, linux and windows archives for amd64 and arm64 are on the releases page, each covered by a keyless cosign signature over checksums.txt.

Details for every path: Installation.

Get an app id and hash from my.telegram.org — the public builds carry no credentials — then register the server:

claude mcp add mcp-tg --env TELEGRAM_APP_ID=12345 --env TELEGRAM_APP_HASH=your_app_hash -- mcp-tg

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. To keep the 2FA password out of the MCP client, run mcp-tg login in a terminal once instead — see Authentication.

Running many agent sessions or several MCP clients? A server process per session adds up — run one shared HTTP daemon instead: brew services start mcp-tg, then claude mcp add --transport http mcp-tg http://127.0.0.1:8787 --scope user. See Transport modes.

Or skip the steps entirely: tell your agent to read Agent Setup and it does the rest.

Everything lives at mcp-tg.lexfrei.dev:

• Tools — the full 80-tool reference
• Configuration — environment variables and flags
• Authentication — login, session storage, revoked-session recovery
• Messages — output format, parseMode, markdown limitations
• Peers — identifier format and resolution
• Search — server-side filters and pagination
• Resources and prompts — including chat subscriptions
• Posting as a channel and Reactions
• Building — requirements, building from source, transport modes

The site is built from docs/ with MkDocs Material and deploys on every push to master. Dependencies are locked in requirements-docs.txt (pinned and hashed; edit requirements-docs.in and recompile). To preview locally:

pip install --requirement requirements-docs.txt
mkdocs serve

Parts of the docs are pinned against the code by cmd/mcp-tg/docs_contract_test.go — the tool list, the annotation census, the search filter values and the parseMode contract fail the test suite when they drift from what the server actually registers. Keep the heading and bullet shapes when editing those pages.

BSD 3-Clause License