tayugram-mcp

Version 1.0.0 · created 13 September 2026 · Apache-2.0 · © 2026 MRsuperkosmos

An MCP server that gives an AI agent (Claude Code, or any MCP client) programmatic access to your own Telegram account over MTProto (GramJS), plus AyuGram Desktop extras and Windows power/anti‑throttle utilities.

200 tools (146 read / 54 write). Writes are serialized through a human‑like, rate‑limited queue. No bot token and no third‑party service — it talks to Telegram directly with your own API credentials and a session that stays on your machine.

⚠️ Disclaimer — read before use

This is a user‑account automation tool (a "userbot") plus a reader for AyuGram's local message archive. By using it you agree that:

• You use it at your own risk. Automating a user account can violate the Telegram Terms of Service and may get the account limited or banned. Keep volumes low and human‑like.

• It is for your own account and personal use. Do not use it for spam, mass messaging, scraping other people's data, harassment, or anything illegal in your jurisdiction.

• The AyuGram tools read data AyuGram already stored locally (including messages other people deleted). Respect other people's privacy and applicable law.

• The software is provided "AS IS", without warranty (see LICENSE). The author is not liable for account bans, data loss, or misuse.

Not affiliated with Telegram or the AyuGram project.

Related MCP server: Telegram MCP Server

Features

Multi‑account: configure several accounts and switch with tg_use_account.

👉 Full command reference: every one of the 200 tools is listed, numbered, with its description in TOOLS.md.

Documentation

• INSTALL.md — step‑by‑step install for people.

• AGENT-INSTALL.md — setup notes for AI agents.

• TOOLS.md — all 200 tools, numbered, with descriptions.

• docs/tdata-import.md — optional: import an existing tdata folder.

Requirements

• Node.js ≥ 18 for the Telegram (tg_*) tools — cross‑platform.

• The AyuGram archive tools (ayu_*) additionally need Node 24+ (or Node 22.5+ with --experimental-sqlite) for the built‑in node:sqlite, plus Windows. If SQLite is unavailable the server still starts and all tg_* tools work; only the AyuGram DB tools return a clear error.

• A Telegram api_id / api_hash from https://my.telegram.org → API development tools.

• (Optional, advanced) Python 3.12 with opentele + Telethon for importing existing Telegram Desktop / AyuGram tdata folders — see docs/tdata-import.md.

Install

git clone https://github.com/MRsuperkosmos/tayugram-mcp
cd tayugram-mcp
npm install

For a detailed walkthrough see INSTALL.md; AI agents doing the setup should read AGENT-INSTALL.md.

Configure & log in

Config and the session live in %USERPROFILE%\.telegram-mcp\ (config.json, session-<id>.txt). **These files are a full login to your account — never commit or share them.** They are already covered by .gitignore.

Interactive login from a terminal:

node src/login.js

It asks for your api_id/api_hash (once), phone number, the login code (sent to another logged‑in Telegram app or by SMS), and your 2FA password if you have one.

Or drive it from the agent: tg_configure {apiId, apiHash} → tg_login_start {phone} → tg_login_code {code} → tg_login_password {password} (if 2FA).

Environment overrides: TG_API_ID, TG_API_HASH, TG_DATA_DIR, TG_ACCOUNT, AYUGRAM_DIR, AYUGRAM_DOWNLOADS, TG_MIN_GAP_MS, TG_MAX_GAP_MS, TG_MAX_PER_MINUTE.

Register with Claude Code

claude mcp add --scope user telegram -- node /absolute/path/to/tayugram-mcp/src/server.js

Any MCP client works — point it at node src/server.js (stdio transport).

Chat references

Every chat argument accepts: @username, a numeric id (users positive, channels -100…, bare channel ids are also tried with -100), +phone, a t.me/... link, me (Saved Messages), or part of a dialog title.

AyuGram archive

ayudata.db stores dialogId the way AyuGram does: users positive, groups/channels negative without the -100 prefix (e.g. -1001234567890); the ayu_* tools also accept the -100… form. Pass resolveNames: true to resolve ids to titles/senders via the live session.

Keeping the PC awake / AyuGram responsive

Windows throttles minimized apps (EcoQoS), which can freeze AyuGram's update loop. Tools: ayu_unthrottle, ayu_keep_responsive (background supervisor), system_prevent_sleep / system_allow_sleep / system_power_status. There are also standalone scripts in tools/ (keep-awake.ps1, unthrottle.ps1, ayu-supervisor.ps1).

Safety design

• No destructive account operations. There are no tools to delete the account, delete or leave groups/channels, delete other people's messages, grant admin rights, ban members, or terminate sessions.

• tg_delete_my_messages only ever deletes your own messages.

• tg_raw is read‑only — it only allows Get* / Search* / Check* / Resolve* / Load* query methods.

• Mutating calls go through a jittered, rate‑limited queue (defaults: 1.5–4 s gap, ≤20/min) and back off on FLOOD_WAIT.

Development & testing

npm test          # offline self‑test: queue, tool registry (200), AyuGram DB, MCP boot
node src/cli.js tg_status       # call any tool from the shell (args as JSON or @file.json)
node src/cli.js tg_list_accounts

The test-*.mjs scripts are live integration tests: they need a logged‑in account and write only to your Saved Messages with a [MCP-TEST] marker (cleaned up afterward). Targets and local file paths are configured via env vars (TG_TEST_USER, TG_TEST_CHANNEL, TG_TEST_IMG, TG_TEST_OUT, TG_ACCOUNT, …) so they contain no personal data.

License

Apache License 2.0 — see LICENSE and NOTICE. © 2026 MRsuperkosmos.