README
¶
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 log in once and register the server:
export TELEGRAM_APP_ID=12345
export TELEGRAM_APP_HASH=your_app_hash
# Interactive terminal login. Phone, code and 2FA password are read from the
# TTY and never touch MCP; the session lands in the OS keychain.
mcp-tg login
# One server process per client, over stdio:
claude mcp add mcp-tg -- mcp-tg
Serving several MCP clients at once? Run one shared HTTP daemon instead of a process each — brew services start mcp-tg, then claude mcp add --transport http mcp-tg http://127.0.0.1:8787 --scope user. See Transport modes.
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
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
mcp-tg
command
Package main provides the entry point for the mcp-tg MCP server.
|
Package main provides the entry point for the mcp-tg MCP server. |
|
internal
|
|
|
completions
Package completions provides MCP completion handlers for argument autocompletion.
|
Package completions provides MCP completion handlers for argument autocompletion. |
|
config
Package config provides configuration loading from environment variables.
|
Package config provides configuration loading from environment variables. |
|
middleware
Package middleware provides MCP middleware for the mcp-tg server.
|
Package middleware provides MCP middleware for the mcp-tg server. |
|
prompts
Package prompts provides MCP prompt templates for common Telegram operations.
|
Package prompts provides MCP prompt templates for common Telegram operations. |
|
resources
Package resources provides MCP resource handlers for Telegram data.
|
Package resources provides MCP resource handlers for Telegram data. |
|
telegram
Package telegram provides a Telegram Client API abstraction.
|
Package telegram provides a Telegram Client API abstraction. |
|
testutil
Package testutil provides test utilities for the mcp-tg project.
|
Package testutil provides test utilities for the mcp-tg project. |
|
tools
Package tools provides MCP tool handlers for Telegram operations.
|
Package tools provides MCP tool handlers for Telegram operations. |