telegram-mcp-kit

Connect an agent to the user's own Telegram account in about 15 minutes, on top of the upstream server chigwell/telegram-mcp. The full step-by-step agent prompt is PROMPT.md in this repo; this skill is the short form.

Steps

0. Check git and uv (uv --version); install uv if missing.
1. Ask the user for api_id and api_hash (from https://my.telegram.org, API development tools). Treat api_hash like a password.
2. git clone https://github.com/chigwell/telegram-mcp.git <MCP_DIR> then uv sync.
3. Patches are pinned to upstream a008ac2: git checkout a008ac2, then git apply <KIT_DIR>/patches/0001-transport-sse-env.patch and 0002-extra-tools-multiaccount.patch. On latest upstream skip 0001 (transport is env-selectable natively) and try git apply -3 for 0002; report conflicting hunks instead of skipping them.
4. Session string: the user runs uv run session_string_generator.py in a real interactive terminal (phone + code or QR). You cannot do this step for them.
5. Create a media folder and pass it as a trailing positional argument to main.py. Without it download_media and send_file silently refuse.
6. Register with the venv python directly, not uv run (on Windows uv run leaks orphan processes):

   claude mcp add telegram --scope user --env TELEGRAM_API_ID=<id> --env TELEGRAM_API_HASH=<hash> --env TELEGRAM_SESSION_STRING=<string> -- <MCP_DIR>/.venv/Scripts/python.exe <MCP_DIR>/main.py <MEDIA_DIR>
   

   Optional read-only default: --env TELEGRAM_EXPOSED_TOOLS=read-only.
7. Restart the session, call get_me, then list_chats with limit 5, and report both.
8. Many parallel sessions on one machine: run one shared daemon (MCP_TRANSPORT=sse, MCP_HOST=127.0.0.1, MCP_PORT=8765) and register {"type":"sse","url":"http://127.0.0.1:8765/sse"}. Use the watchdog in daemon/ (two probes with a pause, evidence before restart); a naive restart blinds every live session.

Rules

• The session string is full account access. Keep it only in the MCP registration env; never in git, logs, synced folders or the final report. Revoke in Telegram, Settings, Devices.
• Never copy one session string to a second machine: AuthKeyDuplicated drops both. Each machine logs in once.
• database is locked means another copy is running (often an orphan). Kill it; do not regenerate the session.
• Throttle bulk reads and downloads; flood-wait locks are real.
• Private groups have no @username: use search_dialogs (patch 0002) and match chats by numeric ID.

More: README.md, PROMPT.md, docs/GOTCHAS.md, docs/SECURITY.md, daemon/README.md.

<!--kit-footer-->

---

Like this skill? It is one of 100 in second-brain-starter-kit: the second brain we built for ourselves and run every day at Palo Alto AI Research Lab. Install the whole set with npx skills add tonydzi/second-brain-starter-kit. Everything is open source and free, so take what you need.

Flagships worth a look on their own: secondop-panel (a second opinion from a panel of external models), claude-memory-tidy (stop your agent's memory from rotting), telegram-mcp-kit (your own Telegram over MCP in about 15 minutes).

Author: Anton Dziatkovskii, Palo Alto AI Research Lab. Telegram @tonydzi - WhatsApp +1 341 222 9178 - X [аккаунт]

Engineers: want to test-drive this setup? Message me. I hand out free starter seeds to engineers who test and report back, and custom skill requests are welcome.