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