The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the TG multi Account MCP listing page.
A self-hosted Model Context Protocol server that lets AI agents work with Telegram through explicitly selected user accounts and optional bots. Accounts are connected in a local web wizard by scanning a QR code and entering a Telegram 2FA password when required.
The server is designed as an agent tool rather than a Telegram client. It can search chat history, read folders and threads, download attachments, track updates, create drafts, and send messages. Every operation names the account or bot it uses; the server never silently selects a sender.
[!IMPORTANT] A Telegram session can access the corresponding account. Run this service on infrastructure you control, protect the state directory and MCP tokens, and give agent tokens only the permissions they need.
This is an unofficial integration that uses the Telegram API and is not affiliated with or endorsed by Telegram.
read, send, and admin permissions plus identity/chat allowlists.The current release exposes 44 MCP tools. See the tool catalog for the full list and behavior notes.
api_id and api_hash from
my.telegram.orgDocker and a domain are required only for the Compose deployment.
Install the published package:
For development from a source checkout:
setup requests the Telegram API credentials through local terminal input and generates a
random MCP access token. It does not request your phone number or account password.
Open http://127.0.0.1:8765/ and follow the account wizard:
Repeat the wizard to add more accounts. Bots are optional and are added separately in the dashboard. Their tokens are verified with Telegram before storage.
The state directory defaults to ~/.local/share/tg-mcp. Override it with --state-dir or
TG_MCP_STATE_DIR.
Print the main token locally:
Configure the client to use the Streamable HTTP endpoint and Bearer header:
The surrounding configuration shape depends on the MCP client. Clients that require OAuth and cannot set a Bearer header are not currently supported.
Start with get_capabilities, list_accounts, and list_bots. All account and bot operations
require an explicit stable ID such as acct_… or bot_….
For a folder-oriented request such as “show today’s messages in ITQ that concern my tasks,” an
agent can call list_folders, then get_folder_messages with matching date_from and date_to
values and an IANA timezone such as Europe/Madrid, provided that processing this content is
permitted under the consent requirements below.
This repository also ships a Codex plugin with authenticated automatic service discovery and a workflow skill for chat resolution, folder summaries, complete pagination, attachments, drafts, and idempotent sending.
The plugin sends an authenticated discovery request to the local machine and network. Discovery
requests and replies are authenticated using the configured MCP token; the token itself is never
broadcast or sent before the discovered endpoint is authenticated. Set TG_MCP_URL to skip
discovery and use a specific HTTPS endpoint. See the
Codex plugin guide for server setup and example prompts.
When Codex and the service run as the same OS user on one machine, the bridge reads the token from
the protected local state automatically. For a service on another machine, provide
TG_MCP_TOKEN to the Codex process.
Operators must comply with the Telegram API Terms and Content Licensing Terms. In particular:
api_id;Installing this software does not grant rights to Telegram content. Use synthetic data, your own saved messages, or chats where the required consent has been obtained and remains valid.
The token generated by setup is the administrative token. Use create_agent_token to issue a
separate token for each agent and restrict it by:
read, send, or admin;Only a SHA-256 hash of an agent token is retained, and the plaintext token is returned once.
Revoke access with revoke_agent_token. A chat-limited token cannot use aggregate inbox, folder,
or global-search tools because those operations could reveal neighboring chats.
For a trusted private network without the Compose HTTPS proxy, bind the service to the LAN and start it on the LAN:
Open the server's LAN address in a browser. The dashboard does not ask for a token, so every user
who can reach it can view its metadata and manage Telegram identities. Same-origin browser requests
are accepted automatically; a separate frontend origin must be added to
TG_MCP_ALLOWED_ORIGINS. Permit TCP 8765 and discovery UDP 38475 only from trusted networks.
Use a VPN or an authenticating reverse proxy when traffic crosses an untrusted network.
Point a domain at the server and allow inbound TCP 80/443, then run:
Open https://your-domain.example/ for initial setup. The dashboard is intentionally available
without a token; protect the domain with network policy or an authenticating reverse proxy.
Agents still connect to https://your-domain.example/mcp with a Bearer token.
Compose also publishes authenticated UDP discovery on port 38475 and advertises that HTTPS
endpoint to clients on the same private network. Change TG_MCP_DISCOVERY_PORT on both sides when
needed, or set TG_MCP_DISCOVERY=false if local discovery is not part of the deployment.
Caddy terminates HTTPS and does not expose the application port publicly. The application container runs as an unprivileged user with a read-only root filesystem. Run one application replica per state volume.
0700; sensitive files use 0600.Back up the state volume only while the service is stopped and store the backup encrypted. If a session is exposed, revoke it from Telegram → Devices. See SECURITY.md for reporting vulnerabilities and the Russian README for operational details and error codes.
poll_updates keeps its most recent 2,000 events in process memory and resets after restart.Architecture and contributor setup are documented in docs/architecture.md and CONTRIBUTING.md. Release and registry steps are in docs/PUBLISHING.md.
Licensed under the Apache License 2.0.