Newer
Older
gnexus-book / 10-systems / applications / tgclient-mcp.md

owner: gmikcon status: active last_reviewed: 2026-11-14 review_interval: 30d confidence: high

source_of_truth: ssh-host-and-live-verified

tgclient-mcp

Multi-account Telegram user-client (Telethon) with an MCP server and a SPA admin panel. Lets Navi agents read and act on the owner's Telegram accounts through MCP tools instead of raw scripts.

Access

  • MCP endpoint: https://tgclientmcp.gnexus.space/mcp (streamable HTTP, Authorization: Bearer mcp_*; /mcp-protocol/ is a legacy alias).
  • SPA admin: https://tgclientmcp.gnexus.space (SSO via gnexus-auth).
  • Health: GET /api/v1/health.
  • Accounts: id 1 = sukhodolskiy (78389352, owner's main), id 2 = Navi (8781031814, dedicated agent account).
  • Secrets: gnexus-creds secret «tgclient-mcp host SSH (192.168.1.171)»; MCP tokens are issued in the SPA admin (≤10 per user).
  • NOTE (2026-11-14): the service is reachable via tgclientmcp.gnexus.space, but this hostname is absent from the domains inventory and from internal-nginx-proxy proxy_mappings — registration gap to close.

Infrastructure path

Internet -> external-vps -> OpenVPN tunnel -> internal-proxy-vps -> tgclientmcp VM (192.168.1.171:8710)

Deployment

  • Host: tgclientmcp VM (see hosts inventory), LAN 192.168.1.171, SSH ubuntu (fleet password, also sudo via sudo -S).
  • Repo on host: /home/ubuntu/tgclient-mcp (branch master); docker compose single service tgclient, container tgclient-tgclient-1, port 8710→8000, volume data:/data (SQLite WAL tgclient.db; accounts.session_data holds StringSession per account).
  • Update: cd /home/ubuntu/tgclient-mcp && sudo docker compose up -d --build.
  • Local fixes on host from 2026-10-05 (deployed, NOT committed upstream): backend/Dockerfile COPY of frontend/package-lock.json; backend/app/tg/manager.py missing TelegramClient import. Beware git pull overwriting them.

Media handling — big files

  • MCP tool download_media returns data_base64 in the tool response and is capped by TGCLIENT_MEDIA_MAX_BYTES (default 20 MiB) — unsuitable for files >20 MB.
  • Workaround used 2026-11-14 (624 MB .blend): run a script inside the container (Telethon + StringSession read from /data/tgclient.db) → async for chunk in client.iter_download(...) → write to /data/ → docker cp to host /tmp → sshpass scp to the navi host; verify md5 on both ends. Full recipe: navi skill tg-big-file-download.
  • Follow-ups tracked in gntodo project tgclient-mcp (id 29): task #543 — server-side MCP tools download_media_to_disk / upload_file_from_disk; task #544 — navi-side wrapper tg_fetch_file.

Gotchas

  • client.get_messages(ids=[...]) returns a LIST — index [0].
  • iter_download inside async def must be consumed with async for (plain for raises RuntimeError).
  • sudo on the host only via echo '<password>' | sudo -S.
  • Empty TGCLIENT_API_ID= breaks pydantic int parsing (keep the line commented out if unset).
  • ssh_exec action=scp with a named connection currently fails («connect() got multiple values for argument 'host'») — use sshpass scp from a local terminal instead.
  • Compose service name is tgclient (not backend) — docker compose exec tgclient ....