mcp-tg

MCP server for Telegram Client API (MTProto). Provides 78 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

Install

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

brew install lexfrei/tap/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.

Quickstart

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 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.

Documentation

Everything lives at mcp-tg.lexfrei.dev:

• Tools — the full 78-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

Contributing

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.

License

BSD 3-Clause License