{"_id":"grokbot-telegram","_rev":"3-a2210e6de5c9576ff7b21e420cc749d9","name":"grokbot-telegram","dist-tags":{"latest":"0.4.0"},"versions":{"0.3.0":{"name":"grokbot-telegram","version":"0.3.0","keywords":["telegram","mcp","mcp-server","model-context-protocol","bot-api","mtproto","cursor","claude","messaging"],"author":{"name":"Lotus015"},"license":"MIT","_id":"grokbot-telegram@0.3.0","maintainers":[{"name":"lotus015","email":"tmiodrag11@gmail.com"}],"homepage":"https://github.com/Lotus015/grokbot-telegram#readme","bugs":{"url":"https://github.com/Lotus015/grokbot-telegram/issues"},"bin":{"grokbot-telegram":"dist/cli.js"},"dist":{"shasum":"26510d8425ba22e5135a9aeba5322e5ef29555a6","tarball":"https://registry.npmjs.org/grokbot-telegram/-/grokbot-telegram-0.3.0.tgz","fileCount":13,"integrity":"sha512-mgqMMXnFrpRyHVl/wZXYIdxaVpmeCViRdy9lEj2pC9EvohkCNZhp7P2vYxRmrE/NQA4pxyPaL7iO+b7S5jyHtw==","signatures":[{"sig":"MEUCIBocpoa/Rea1xlxj3UgM5q0YBoC6c7PUP9kAF/MCCg/iAiEAn7Ev+h+uNV6ezU0Db3w14i8hcozzgq1S+VZDaOeC70c=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":5328142},"type":"module","engines":{"node":">=20"},"gitHead":"66dfa8cc9146c2a4e35b9723b3bc3abd5cdacf38","scripts":{"test":"npm test --prefix packages/mcp-server && npm test --prefix packages/mcp-user-server","build":"npm run build --prefix packages/mcp-server && npm run build --prefix packages/mcp-user-server && node scripts/build-dist.mjs","smoke":"node scripts/pack-smoke.mjs","validate":"node scripts/validate-plugin.mjs","typecheck":"npm run typecheck --prefix packages/mcp-server && npm run typecheck --prefix packages/mcp-user-server","prepublishOnly":"npm run build && npm test && npm run validate && npm run smoke"},"_npmUser":{"name":"lotus015","email":"tmiodrag11@gmail.com"},"repository":{"url":"git+https://github.com/Lotus015/grokbot-telegram.git","type":"git"},"_npmVersion":"11.6.2","description":"Telegram MCP servers in one command: Bot API (send as your @bot) and MTProto user account (send as you).","directories":{},"_nodeVersion":"24.12.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/grokbot-telegram_0.3.0_1788801574168_0.19381124731107668","host":"s3://npm-registry-packages-npm-production"}},"0.3.1":{"name":"grokbot-telegram","version":"0.3.1","keywords":["telegram","mcp","mcp-server","model-context-protocol","bot-api","mtproto","cursor","claude","messaging"],"author":{"name":"Lotus015"},"license":"MIT","_id":"grokbot-telegram@0.3.1","maintainers":[{"name":"lotus015","email":"tmiodrag11@gmail.com"}],"homepage":"https://github.com/Lotus015/grokbot-telegram#readme","bugs":{"url":"https://github.com/Lotus015/grokbot-telegram/issues"},"bin":{"grokbot-telegram":"dist/cli.js"},"dist":{"shasum":"ff7ebac34517b1564dd550c0fe1de30a2cfc7c0d","tarball":"https://registry.npmjs.org/grokbot-telegram/-/grokbot-telegram-0.3.1.tgz","fileCount":13,"integrity":"sha512-Y9hy6RIwVuorcjet8pNwY+OImKIs0SFBnQCEoToyNLazwKA8IpbFKRJI/gNFJ7Kxde76bSJGWJlQgRmvkVtA5A==","signatures":[{"sig":"MEQCIG2bwoafRnNsHlRs3Umjjw+xlRMZ78ze+EhWWG4lMG0vAiB/vtuxqitX/Lu1I5XO+uXdmvQXabnNltKW9qHPsK0SDA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":5405360},"type":"module","engines":{"node":">=20"},"gitHead":"f3813b27ae8a9b54dd9c20f5a62893b77a0e16e6","scripts":{"test":"npm test --prefix packages/mcp-server && npm test --prefix packages/mcp-user-server","build":"npm run build --prefix packages/mcp-server && npm run build --prefix packages/mcp-user-server && node scripts/build-dist.mjs","smoke":"node scripts/pack-smoke.mjs","validate":"node scripts/validate-plugin.mjs","typecheck":"npm run typecheck --prefix packages/mcp-server && npm run typecheck --prefix packages/mcp-user-server","prepublishOnly":"npm run build && npm test && npm run validate && npm run smoke"},"_npmUser":{"name":"lotus015","email":"tmiodrag11@gmail.com"},"repository":{"url":"git+https://github.com/Lotus015/grokbot-telegram.git","type":"git"},"_npmVersion":"11.6.2","description":"Telegram MCP servers in one command: Bot API (send as your @bot) and MTProto user account (send as you).","directories":{},"_nodeVersion":"24.12.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/grokbot-telegram_0.3.1_1788870312059_0.8099429847252291","host":"s3://npm-registry-packages-npm-production"}},"0.4.0":{"name":"grokbot-telegram","version":"0.4.0","description":"Telegram MCP servers in one command: Bot API (send as your @bot) and MTProto user account (send as you).","license":"MIT","type":"module","author":{"name":"Lotus015"},"homepage":"https://github.com/Lotus015/grokbot-telegram#readme","repository":{"type":"git","url":"git+https://github.com/Lotus015/grokbot-telegram.git"},"bugs":{"url":"https://github.com/Lotus015/grokbot-telegram/issues"},"keywords":["telegram","mcp","mcp-server","model-context-protocol","bot-api","mtproto","cursor","claude","messaging"],"bin":{"grokbot-telegram":"dist/cli.js"},"engines":{"node":">=20"},"publishConfig":{"access":"public"},"scripts":{"build":"npm run build --prefix packages/mcp-server && npm run build --prefix packages/mcp-user-server && node scripts/build-dist.mjs","test":"npm test --prefix packages/mcp-server && npm test --prefix packages/mcp-user-server","typecheck":"npm run typecheck --prefix packages/mcp-server && npm run typecheck --prefix packages/mcp-user-server","validate":"node scripts/validate-plugin.mjs","prepublishOnly":"npm run build && npm test && npm run validate && npm run smoke","smoke":"node scripts/pack-smoke.mjs"},"gitHead":"79d81dba9e40755d9a523d729e35017b4989d170","_id":"grokbot-telegram@0.4.0","_nodeVersion":"24.12.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-Wp0d3wYUIEpXJp23rfCsg9jOe9vaEaKG94J9l+jTO6wZWXMjt+c11lWrESm6f8wJC0djcvmTv4UY5EKkq98izQ==","shasum":"26ec9705247409a937d17d6a616104184e0c8b0d","tarball":"https://registry.npmjs.org/grokbot-telegram/-/grokbot-telegram-0.4.0.tgz","fileCount":13,"unpackedSize":5410991,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCPKkGVC+iO2uH1ArjIpkxpqin1T9m6hxZqG+f42Pd43QIgYJbiWhYbg7rMz5XEXBPVSFaA1MBYBjkU//GJp+33N90="}]},"_npmUser":{"name":"lotus015","email":"tmiodrag11@gmail.com"},"directories":{},"maintainers":[{"name":"lotus015","email":"tmiodrag11@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/grokbot-telegram_0.4.0_1788884856516_0.9464966643791903"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-07T17:19:34.023Z","modified":"2026-09-08T16:27:36.873Z","0.3.0":"2026-09-07T17:19:34.339Z","0.3.1":"2026-09-08T12:25:12.334Z","0.4.0":"2026-09-08T16:27:36.690Z"},"bugs":{"url":"https://github.com/Lotus015/grokbot-telegram/issues"},"author":{"name":"Lotus015"},"license":"MIT","homepage":"https://github.com/Lotus015/grokbot-telegram#readme","keywords":["telegram","mcp","mcp-server","model-context-protocol","bot-api","mtproto","cursor","claude","messaging"],"repository":{"type":"git","url":"git+https://github.com/Lotus015/grokbot-telegram.git"},"description":"Telegram MCP servers in one command: Bot API (send as your @bot) and MTProto user account (send as you).","maintainers":[{"name":"lotus015","email":"tmiodrag11@gmail.com"}],"readme":"# Telegram for Cursor\n\n[![npm](https://img.shields.io/npm/v/grokbot-telegram.svg)](https://www.npmjs.com/package/grokbot-telegram)\n[![CI](https://github.com/Lotus015/grokbot-telegram/actions/workflows/ci.yml/badge.svg)](https://github.com/Lotus015/grokbot-telegram/actions/workflows/ci.yml)\n[![license](https://img.shields.io/npm/l/grokbot-telegram.svg)](LICENSE)\n\nInstallable [Cursor plugin](https://cursor.com/docs/plugins) with **two** first-party MCP servers:\n\n| Mode | MCP server | Identity | Protocol |\n| --- | --- | --- | --- |\n| **Bot** | `telegram-bot` | Your [@BotFather](https://t.me/BotFather) bot | Official [HTTP Bot API](https://core.telegram.org/bots/api) |\n| **User account** | `telegram-user` | **Your personal Telegram account** | [MTProto](https://core.telegram.org/mtproto) via [teleproto](https://github.com/sanyok12345/teleproto) (maintained [GramJS](https://github.com/gram-js/gramjs) fork) |\n\nUse one or both. v0.2.0 kept the v0.1.0 Bot API path and added user-account login; v0.3.0 ships both servers as the single npm package `grokbot-telegram` and appends a disclaimer footer to every outgoing message.\n\nThis is **not** Bot API–only, and it is **not** user-account–only. Marketplace copy: a Cursor plugin that can send/read Telegram as a bot **and/or** as the logged-in user.\n\n## Which mode should I use?\n\n| Need | Mode |\n| --- | --- |\n| Notifications, CI alerts, channel posts as `@mybot` | **Bot API** — `TELEGRAM_BOT_TOKEN` |\n| “Send this in **my** name”, read my real chats / dialog list | **User account** — `TELEGRAM_API_ID` + `TELEGRAM_API_HASH` + session |\n| Both (bot for alerts, account for DMs) | Configure **both** variable sets |\n\nBot API **cannot** list your personal inbox. User-account mode **can** (`list_dialogs`), because it is logged in as you.\n\n## What you must provide\n\n### Bot API (`telegram-bot`)\n\n1. Create a bot with [@BotFather](https://t.me/BotFather) → `/newbot`.\n2. Set **`TELEGRAM_BOT_TOKEN`** in Cursor **Plugins → Configure**.\n3. Open a DM with the bot and tap **Start** (`/start`). Bots cannot message you first.\n\nNo `api_id` is required for this mode.\n\n### User account (`telegram-user`) — first run\n\n1. Open [https://my.telegram.org/apps](https://my.telegram.org/apps), log in with the **same phone** as the Telegram account you want to use, and create an app.\n2. Set **`TELEGRAM_API_ID`** and **`TELEGRAM_API_HASH`** in **Plugins → Configure**.\n3. Complete **one-time login** (phone + code, QR / Link Desktop Device, or an existing session string).\n4. Persist the session as **`TELEGRAM_SESSION`** and/or the file `~/.grokbot-telegram/user.session` (mode `0600`).\n\nYou will be asked for api_id / api_hash / login on first run. A bot token is **not** used for this server.\n\n**The session is full account access.** Treat it like a password. Never commit it.\n\n## Message disclaimer\n\nEvery message sent through either server carries a footer, so the person on the other end knows an agent — not a human typing — produced it:\n\n```\nyour message text\n\n— sent by grokbot-telegram on my behalf\n```\n\nThe Bot API server uses `— sent by grokbot-telegram` (it is already visibly a bot). `TELEGRAM_DISCLAIMER` controls it:\n\n| Value | Result |\n| --- | --- |\n| unset | default wording above |\n| any text | that text is used verbatim |\n| `off`, `false`, `0`, `no`, `none`, empty | no footer |\n\nThe wording names the package rather than linking to it, on purpose. A URL in the footer would make Telegram attach a link-preview card to every message you send, and a link in someone's personal chat reads as advertising — the name is still searchable on npm and GitHub. Set `TELEGRAM_DISCLAIMER` to a URL yourself if you disagree.\n\nTwo details worth knowing:\n\n- The footer counts against Telegram's 4096-character limit. If text + footer would exceed it, the send is **refused** with an error naming the overflow rather than quietly truncating your words or dropping the footer.\n- With `parse_mode`, the footer is escaped for that mode. This matters for `MarkdownV2`, where an unescaped `.` or `-` makes Telegram reject the whole message.\n\n## Why you need your own api_id\n\nTelegram issues `api_id`/`api_hash` per developer and rejects credentials that have been published: an app that ships a shared pair earns its users an [`API_ID_PUBLISHED_FLOOD`](https://core.telegram.org/api/obtaining_api_id) error at login. So this package deliberately does not ship one. It is a one-time, two-minute detour at [my.telegram.org/apps](https://my.telegram.org/apps), and it keeps the blast radius at one user instead of everyone at once.\n\nYou do not have to put the values in a config file. Hand them to the agent and it calls `save_api_credentials`, which writes them next to the session at mode `0600`. `TELEGRAM_API_ID` / `TELEGRAM_API_HASH` still work as environment variables and take precedence, which is the path for developers bringing their own app.\n\n**Only user-account mode needs this.** Bot API mode needs nothing but a [@BotFather](https://t.me/BotFather) token, which takes about thirty seconds inside Telegram. If you only want notifications or to post to a channel, use that.\n\n## Forum topics\n\nGroups with topics turned on keep their messages in separate threads. `list_dialogs` marks those with `isForum`, `list_forum_topics` lists the threads, and `send_message` / `get_messages` take an optional `topic_id` to work inside one. Without `topic_id` nothing changes — the message goes to the chat as before.\n\nA wrong `topic_id` is worth understanding: Telegram does not reject it, it quietly files the message under General, in front of everyone. So `send_message` checks the id against the topic list before sending, and refuses a closed topic outright. That costs one extra call, only when a topic is named.\n\n## Naming a chat\n\n`send_message` and `get_messages` take an id, `me`, an `@username`, or a chat title. Ids and `@usernames` go straight out. A title is resolved against your dialog list first, and an ambiguous one is refused with the candidates named rather than guessed at.\n\nThis exists because handing a title to the underlying client makes it look for a username that was never there, which in a short-lived process means a minute of hanging instead of an error. Prefer an id from `list_dialogs` when you have one: it is the only form with no lookup at all.\n\n## Security\n\n### Bot token\n\nAnyone with `TELEGRAM_BOT_TOKEN` can send as that bot, read updates, and change bot settings. Set it only in Plugins → Configure. The bot MCP redacts token-shaped strings from errors.\n\n### User session (stronger warning)\n\n- A GramJS **session string** or session file is equivalent to being logged in on a new device.\n- Anyone who has it can **read your chats and send as you**.\n- Never commit `TELEGRAM_SESSION`, `api_hash`, `.env`, or `*.session` files.\n- After first login, save the session in Plugins → Configure or keep the `0600` session file. Do not leave the string in chat history if you can avoid it.\n- Revoke: Telegram → **Settings → Devices** → terminate the unknown session, then delete the session file / clear the variable.\n- Automating a user account is a Telegram ToS gray area. Keep sends human-paced. No spam or bulk broadcast.\n\nThe repo never contains real tokens, api hashes, or sessions. `mcp.json` only has `${VAR}` placeholders that match the manifest.\n\n## MCP tools\n\n### `telegram-bot` (unchanged Bot API v1)\n\n| Tool | Telegram method | Purpose |\n| --- | --- | --- |\n| `send_message` | `sendMessage` | Send text as the **bot** (`chat_id` or public `@username`) |\n| `get_me` | `getMe` | Confirm the token; bot username |\n| `get_updates` | `getUpdates` | Debug recent updates |\n| `list_recent_chats` | derived from `getUpdates` | Best-effort recent chats (not a full inbox) |\n\n### `telegram-user` (MTProto)\n\n| Tool | Purpose |\n| --- | --- |\n| `save_api_credentials` | Store api_id / api_hash at 0600 so no config file is needed |\n| `auth_status` | Credentials + whether the session is authorized |\n| `start_login` / `complete_login` | Phone + login code (+ optional 2FA password) |\n| `start_qr_login` / `complete_qr_login` | QR / Link Desktop Device (+ optional 2FA) |\n| `get_me` | Logged-in **user** (not a bot) |\n| `list_dialogs` | Real dialog / inbox list, `isForum` marks groups with topics |\n| `list_forum_topics` | Topics of a forum group, with the ids to send into |\n| `search_dialogs` | Filter dialogs by title, username, or id |\n| `get_messages` | Recent history for a chat |\n| `send_message` | Send text **as the user** (`me`, `@username`, dialog id, or a chat title) |\n\nBoth servers expose `send_message` and `get_me`. Prefer the MCP server name (`telegram-bot` vs `telegram-user`). Tool descriptions are prefixed `[Bot API]` or `[User account]`.\n\n## Skills\n\n- **telegram-mode-guide** — when to use bot vs user\n- **telegram-bot-setup** — BotFather, `TELEGRAM_BOT_TOKEN`, smoke-test\n- **send-telegram-message** — send as the bot; confirm first\n- **telegram-user-setup** — my.telegram.org, first login, session persistence\n- **send-telegram-user-message** — resolve from the dialog list; confirm first\n\n## Install\n\n### Any MCP client (`npx`)\n\nBoth servers ship as one npm package, [`grokbot-telegram`](https://www.npmjs.com/package/grokbot-telegram), behind a single command:\n\n```bash\nnpx grokbot-telegram bot     # Bot API server over stdio\nnpx grokbot-telegram user    # user-account (MTProto) server over stdio\nnpx grokbot-telegram login   # interactive login, prints a TELEGRAM_SESSION\n```\n\nWith no command the mode is read from the environment: `TELEGRAM_BOT_TOKEN` selects `bot`, `TELEGRAM_API_ID` + `TELEGRAM_API_HASH` select `user`. If both are set it refuses to guess and asks for an explicit mode.\n\nDrop this into any MCP client config (Claude Code, Claude Desktop, Cursor, …):\n\n```json\n{\n  \"mcpServers\": {\n    \"telegram-bot\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"grokbot-telegram\", \"bot\"],\n      \"env\": { \"TELEGRAM_BOT_TOKEN\": \"…\" }\n    },\n    \"telegram-user\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"grokbot-telegram\", \"user\"],\n      \"env\": {\n        \"TELEGRAM_API_ID\": \"…\",\n        \"TELEGRAM_API_HASH\": \"…\",\n        \"TELEGRAM_SESSION\": \"…\"\n      }\n    }\n  }\n}\n```\n\n### Cursor Marketplace (when listed)\n\n1. Open **Customize** → search **telegram-bot**, or visit [cursor.com/marketplace](https://cursor.com/marketplace).\n2. Install the plugin.\n3. **Plugins → Configure** → set the variables for the mode(s) you want.\n\n### From this repository\n\n```bash\nmkdir -p ~/.cursor/plugins/local\nln -s /path/to/grokbot-telegram ~/.cursor/plugins/local/telegram-bot\n```\n\nReload the window (**Developer: Reload Window**). Team / Enterprise admins may need to allow local plugin imports.\n\nNote that `mcp.json` launches the servers through `npx grokbot-telegram`, so a symlinked clone still runs the **published** build, not your working tree. To exercise local changes, either `npm run build && npm link` in the repo root, or point `mcp.json` at `${PLUGIN_ROOT}/dist/bot.js` and `${PLUGIN_ROOT}/dist/user.js` with `\"command\": \"node\"` while you work (`npm run validate` will flag that, which is the reminder to change it back).\n\nSubmit the public repo at [cursor.com/marketplace/publish](https://cursor.com/marketplace/publish) and/or list it on [cursor.directory](https://cursor.directory).\n\n## Configure\n\nThe plugin declares variables in `.cursor-plugin/plugin.json` and substitutes `${VAR}` placeholders in `mcp.json`. None are required in the schema so you can enable only one mode.\n\n| Variable | Mode | Where to get it |\n| --- | --- | --- |\n| `TELEGRAM_BOT_TOKEN` | Bot | [@BotFather](https://t.me/BotFather) |\n| `TELEGRAM_API_ID` | User | [my.telegram.org/apps](https://my.telegram.org/apps) — or let the agent store it, see below |\n| `TELEGRAM_API_HASH` | User | [my.telegram.org/apps](https://my.telegram.org/apps) — or let the agent store it, see below |\n| `TELEGRAM_SESSION` | User | Returned after first login (optional if the session file exists) |\n| `TELEGRAM_DISCLAIMER` | Both | Optional. Footer wording, or `off` to disable (see below) |\n\nOptional env (not a marketplace variable): `TELEGRAM_SESSION_PATH` overrides the default session file `~/.grokbot-telegram/user.session`.\n\nLogin is two calls — `start_login` sends the code, `complete_login` redeems it — and some MCP hosts start a fresh process per call. So the in-flight state is written next to the session file as `user.session.pending.json` (mode 0600) and picked back up by the next process. It holds a pre-authorization session: it cannot read or send anything, but it is the auth key the code is bound to, so it is deleted the moment login succeeds and discarded after 15 minutes.\n\n**QR login does not survive a restart, and cannot.** Telegram announces the scan on the connection that exported the code, and the authorization only exists once that same connection redeems it. The process that called `start_qr_login` has to stay alive until the scan lands. On a host that starts a process per tool call, use phone login. `complete_qr_login` still adopts an already-authorized session if there is one, and otherwise hands back a fresh `login_url`, because exporting again yields a *different* code and re-showing the old one can never work.\n\nThe project was called `cursor-telegram-plugin` before it became `grokbot-telegram`. A session left in the old `~/.cursor-telegram-plugin/user.session` is still read, so an existing login keeps working; new sessions are written to the new path.\n\n## Example prompts\n\n**Bot**\n\n- “Verify my Telegram bot with `telegram-bot` `get_me`. Do not print the token.”\n- “I just /start’ed the bot. List recent chats, then send ‘hello from Cursor’ to my DM after I confirm.”\n\n**User**\n\n- “I want messages sent as me, not as a bot. Walk me through my.telegram.org and first login.”\n- “Search my Telegram dialogs for ‘Ada’, then send this text after I confirm.”\n- “Show recent messages in Saved Messages (`me`) using the user account.”\n\n## How to test\n\n### Bot API `send_message`\n\n1. `/start` the bot (or add it to a group/channel).\n2. Set `TELEGRAM_BOT_TOKEN`.\n3. In Agent chat: `get_me` → `list_recent_chats` → confirm → `send_message`.\n4. Optional:\n\n```bash\nexport TELEGRAM_BOT_TOKEN=\"…\"   # local shell only\ncurl -sS \"https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getMe\"\n```\n\n### User-account send (as you)\n\n1. Set `TELEGRAM_API_ID` and `TELEGRAM_API_HASH`.\n2. Login once:\n\n```bash\nexport TELEGRAM_API_ID=\"…\"\nexport TELEGRAM_API_HASH=\"…\"\nnpx grokbot-telegram login\n```\n\nFrom a clone, the equivalent is `node dist/login.js` after `npm run build`.\n\nOr use `start_login` / `start_qr_login` from the agent.\n\nFor login through a chat, prefer `start_login`. A QR token lives about 30 seconds and that clock starts when the tool returns, not when the code reaches the screen — which is usually not enough time in a conversation. The token cannot be extended; it is Telegram's limit. What the tools do instead is remove the round trips. `start_qr_login` and every waiting reply from `complete_qr_login` return the code **as a scannable PNG in the tool result**, ahead of the JSON, so the agent forwards an image rather than rendering one itself — and `login_url` stays in the payload as a fallback for clients that show no images. Each waiting reply also carries a fresh code and `expires_in_seconds`, so a retry gives the user a full window instead of a dead code.\n\nThe QR is drawn locally. A login token is a credential, so it never goes to an external image service.\n\nNot every MCP host paints tool-result images on its own; where it does not, the agent forwards the base64 it was handed. Either way the code is generated once, here, rather than round-tripped through the agent.\n\nThe session shows up in Telegram → Settings → Devices as **grokbot-telegram**, so it is easy to find and revoke.\n\n3. Confirm `get_me` is your user (`isBot: false`).\n4. `list_dialogs` / `search_dialogs`, confirm destination + text, then `send_message`.\n\nAutomated tests mock Telegram (no live token or account). Node.js 20+ is required.\n\n```bash\nnpm install --prefix packages/mcp-server\nnpm install --prefix packages/mcp-user-server\nnpm test          # both packages\nnpm run typecheck\nnpm run build     # per-package bundles, then collected into the root dist/\nnpm run validate  # manifest + wiring invariants\n```\n\nWorking on this with a coding agent? Start from [AGENTS.md](AGENTS.md).\n\n## Chat list limitation (Bot API only)\n\nThe Bot API **cannot** list every chat a bot belongs to. `list_recent_chats` only inspects recent `getUpdates` events. If nothing shows up: the user has not `/start`ed the bot, the group is quiet, or a **webhook** is set.\n\nUser-account mode uses the real dialog list and does not have this limitation.\n\n## Why first-party servers (not a random npm MCP)\n\nPublic packages exist (Bot API wrappers; user MCPs such as [`@overpod/mcp-telegram`](https://www.npmjs.com/package/@overpod/mcp-telegram) / [mcp-telegram/mcp-telegram](https://github.com/mcp-telegram/mcp-telegram)). They are real, but they are either very large or a different product.\n\nThis plugin ships two small stdio servers:\n\n- **Bot:** official HTTP Bot API only (`packages/mcp-server`)\n- **User:** teleproto MTProto user client (`packages/mcp-user-server`), tools limited to login, dialogs, history, and send\n\nBoth are bundled with esbuild — every dependency (including teleproto) is inlined, so the published package installs with zero runtime dependencies. `npm run build` produces the per-package bundles and collects them into the publishable root `dist/`:\n\n- `dist/bot.js`, `dist/user.js`, `dist/login.js` — the bundles\n- `dist/cli.js` — the `grokbot-telegram` dispatcher that picks between them\n\n```bash\nnpm run build\n```\n\n`mcp.json` launches both:\n\n```json\n{\n  \"telegram-bot\": {\n    \"command\": \"npx\",\n    \"args\": [\"-y\", \"grokbot-telegram\", \"bot\"],\n    \"env\": { \"TELEGRAM_BOT_TOKEN\": \"${TELEGRAM_BOT_TOKEN}\" }\n  },\n  \"telegram-user\": {\n    \"command\": \"npx\",\n    \"args\": [\"-y\", \"grokbot-telegram\", \"user\"],\n    \"env\": {\n      \"TELEGRAM_API_ID\": \"${TELEGRAM_API_ID}\",\n      \"TELEGRAM_API_HASH\": \"${TELEGRAM_API_HASH}\",\n      \"TELEGRAM_SESSION\": \"${TELEGRAM_SESSION}\"\n    }\n  }\n}\n```\n\n## Marketplace notes\n\n- Single Cursor Plugin (`.cursor-plugin/plugin.json`), not a multi-plugin `marketplace.json` repo.\n- **MTProto user client + Bot API**, not Bot API alone.\n- Plugin `name` remains `telegram-bot` for continuity with v0.1.0; product copy and `displayName` describe both modes.\n- Version `0.3.0`, MIT, logo at `assets/logo.svg`.\n- Variables: `TELEGRAM_BOT_TOKEN`, `TELEGRAM_API_ID`, `TELEGRAM_API_HASH`, `TELEGRAM_SESSION`, `TELEGRAM_DISCLAIMER` (all optional in the schema).\n- Submit: [cursor.com/marketplace/publish](https://cursor.com/marketplace/publish).\n\n## Layout\n\n```text\n.\n├── .cursor-plugin/plugin.json\n├── mcp.json\n├── skills/\n│   ├── telegram-mode-guide/SKILL.md\n│   ├── telegram-bot-setup/SKILL.md\n│   ├── send-telegram-message/SKILL.md\n│   ├── telegram-user-setup/SKILL.md\n│   └── send-telegram-user-message/SKILL.md\n├── assets/logo.svg\n├── AGENTS.md                   # guidance for coding agents (CLAUDE.md points here)\n├── src/cli.js                  # grokbot-telegram dispatcher (bot | user | login)\n├── dist/                       # published bundles, built (gitignored)\n├── packages/mcp-server/        # Bot API MCP + dist bundle\n├── packages/mcp-user-server/   # GramJS user MCP + dist bundle\n├── LICENSE\n└── README.md\n```\n\n## License\n\n[MIT](LICENSE) © Lotus / Lotus015 ([GitHub](https://github.com/Lotus015))\n","readmeFilename":"README.md"}