# tayugram-mcp

[![CI](https://github.com/MRsuperkosmos/tayugram-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/MRsuperkosmos/tayugram-mcp/actions/workflows/ci.yml)
[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)

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

An [MCP](https://modelcontextprotocol.io) server that gives an AI agent (Claude Code, or any MCP client) programmatic access to **your own Telegram account** over MTProto ([GramJS](https://gram.js.org)), 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](https://telegram.org/tos) 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.

---

## Features

| Layer | What it does |
|---|---|
| **`tg_*`** (Telegram, MTProto) | Dialogs, unread, global & in‑chat search, full history export, media download, send/edit/delete/forward/react/pin, polls, stickers/GIFs/dice/location/contacts/albums/video‑notes/view‑once, scheduled messages, reactions & readers lists, translation, comment threads, drafts, folders, contacts & privacy, account/sessions/profile, channel statistics, bots & inline bots, stories, and a **read‑only** raw MTProto escape hatch. |
| **`ayu_*`** (AyuGram Desktop) | Read AyuGram's local `ayudata.db`: **deleted** and **edited** message archive, per‑message edit history, search/timeline/export, top dialogs & deleters, ghost‑mode/archiving settings; launch AyuGram and open chats via `tg://` deep links. |
| **`ayu_*` / `system_*`** (Windows power) | Stop the PC sleeping and keep AyuGram responsive while minimized (disables EcoQoS/efficiency‑mode throttling). |

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**](TOOLS.md).

## Documentation

- [INSTALL.md](INSTALL.md) — step‑by‑step install for people.
- [AGENT-INSTALL.md](AGENT-INSTALL.md) — setup notes for AI agents.
- [TOOLS.md](TOOLS.md) — all 200 tools, numbered, with descriptions.
- [docs/tdata-import.md](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`](docs/tdata-import.md).

## Install

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

For a detailed walkthrough see [INSTALL.md](INSTALL.md); AI agents doing the setup should read [AGENT-INSTALL.md](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:

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

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

```bash
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`](LICENSE) and [`NOTICE`](NOTICE). © 2026 MRsuperkosmos.