TG multi-account MCP
Русская документация
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.
What it supports
- Multiple Telegram user accounts, each with its own QR/2FA onboarding flow and session.
- Dashboard controls to disable, reconnect, or permanently delete an account and its local session.
- Optional Telegram bots connected independently through BotFather tokens.
- Streamable HTTP MCP with Bearer-token authentication.
- Chat, folder, message, attachment, mention, topic, reply-thread, and global search tools.
- Cyrillic/Latin transliteration matching when finding chats.
- User and bot sending, edits, scheduling, forwarding, reactions, drafts, and idempotency keys.
- Scoped agent tokens with
read, send, and admin permissions plus identity/chat allowlists.
- A private operations dashboard that records metadata without message text, queries, passwords,
or tokens.
- Docker Compose deployment with Caddy-managed HTTPS.
The current release exposes 44 MCP tools. See the tool catalog for the full
list and behavior notes.
Requirements
Docker and a domain are required only for the Compose deployment.
Quick start
Install the published package:
uv tool install tg-account-mcp
tg-mcp setup
TG_MCP_PORT=8765 tg-mcp serve
For development from a source checkout:
uv sync --frozen
uv run tg-mcp setup
TG_MCP_PORT=8765 uv run tg-mcp serve
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:
- Scan the QR code in Telegram → Settings → Devices → Link Desktop Device.
- Enter the Telegram cloud password if 2FA is enabled.
- Give the account a local display name.
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.
Connect an MCP client
Print the main token locally:
Configure the client to use the Streamable HTTP endpoint and Bearer header:
{
"url": "http://127.0.0.1:8765/mcp",
"headers": {
"Authorization": "Bearer <MCP_TOKEN>"
}
}
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.
Codex plugin
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.
codex plugin marketplace add Mesteriis/tg-account-mcp --ref main
codex plugin add tg-account-mcp@tg-account-mcp
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.
Responsible use and Telegram terms
Operators must comply with the Telegram API Terms and
Content Licensing Terms. In particular:
- obtain and use your own Telegram
api_id;
- do not perform actions on a user's behalf without that user's knowledge and consent;
- do not scrape, index, harvest, aggregate, train on, benchmark with, or otherwise provide
Telegram content to AI/ML systems unless every relevant user has given explicit, informed,
affirmative, and continuing consent for the specific content and context;
- respect the rights, privacy, and instructions of people whose messages or files are accessed.
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.
Agent access control
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:
- scope:
read, send, or admin;
- permitted account and bot IDs;
- permitted chat IDs.
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.
Direct LAN deployment
For a trusted private network without the Compose HTTPS proxy, bind the service to the LAN and
start it on the LAN:
TG_MCP_BIND=0.0.0.0 \
TG_MCP_PORT=8765 \
tg-mcp serve
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.
Docker Compose deployment
Point a domain at the server and allow inbound TCP 80/443, then run:
cp .env.example .env
docker compose build
docker compose run --rm --no-deps tg-mcp setup
docker compose up -d
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.
Security model
- The state directory is required to have mode
0700; sensitive files use 0600.
- Symlinks, hard-linked sensitive files, foreign ownership, and broad permissions are rejected.
- The web UI has no third-party scripts, fonts, analytics, or remote assets.
- Dashboard account data and setup APIs are available without a token to clients that can reach
the server; the MCP endpoint always requires a Bearer token.
- Host and Origin values are checked against exact allowlists; wildcards are rejected.
- Logs and operations history omit message bodies, search terms, credentials, QR URLs, and 2FA
passwords.
- Tests use fake Telegram adapters and never send real messages.
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.
Known limitations
- Secret chats are not available through Telegram's cloud API.
- Message deletion and distributed/multi-replica deployment are not supported.
- History is read from Telegram on demand rather than copied into a local database.
- Positional pagination can repeat or skip items when new messages arrive between pages.
poll_updates keeps its most recent 2,000 events in process memory and resets after restart.
Development
uv sync --frozen
uv run ruff check .
uv run ruff format --check .
uv run pytest -q
uv build
TG_MCP_DOMAIN=mcp.example.test docker compose config --quiet
docker build -t tg-account-mcp:local .
Architecture and contributor setup are documented in docs/architecture.md
and CONTRIBUTING.md. Release and registry steps are in
docs/PUBLISHING.md.
License
Licensed under the Apache License 2.0.