{"_id":"telegram-notify-mcp","_rev":"5-609a55b6ddf1498ef907813ad1c5cc79","name":"telegram-notify-mcp","dist-tags":{"latest":"2.2.1"},"versions":{"1.0.0":{"name":"telegram-notify-mcp","version":"1.0.0","keywords":["mcp","telegram","notifications","botfather","model-context-protocol"],"author":{"url":"https://digitalhand.site","name":"Ehsan Eskandari pour","email":"e.eskandaripour7@gmail.com"},"license":"MIT","_id":"telegram-notify-mcp@1.0.0","maintainers":[{"name":"internetchk","email":"internetchk@gmail.com"}],"homepage":"https://digitalhand.site","bugs":{"url":"https://digitalhand.site/contact","email":"e.eskandaripour7@gmail.com"},"bin":{"telegram-notify-mcp":"dist/index.js"},"dist":{"shasum":"de3482e777d24b8cff06b70afa9a7017faccaedc","tarball":"https://registry.npmjs.org/telegram-notify-mcp/-/telegram-notify-mcp-1.0.0.tgz","fileCount":12,"integrity":"sha512-n5KRcxqwT1zKXaEhTthBNgO9f8rzOZGyGCMGWj7bEBfEty5p+V67rjGVF1lYVIO4ygvCsMABB0D9i8+mf2g5cg==","signatures":[{"sig":"MEQCIAXxoc3WTvua052vFZvEh6XcL4dszC2vxn3HMsOnRiNPAiBuf/+PBd7HZC/6mtOAR7dOYp/jUjzoICI5jcjlvh+YYg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":30823},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=20"},"scripts":{"test":"node --import tsx --test tests/telegram.test.ts","build":"tsc","start":"node dist/index.js","prepare":"tsc"},"_npmUser":{"name":"internetchk","email":"internetchk@gmail.com"},"_npmVersion":"9.2.0","description":"MCP connector/server that sends Telegram notifications via your own BotFather bot (BYOB).","directories":{},"_nodeVersion":"20.19.2","dependencies":{"zod":"^3.23.8","@modelcontextprotocol/sdk":"^1.18.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.0","typescript":"^5.6.0","@types/node":"^20.14.0"},"_npmOperationalInternal":{"tmp":"tmp/telegram-notify-mcp_1.0.0_1788728968273_0.731982457971984","host":"s3://npm-registry-packages-npm-production"}},"2.0.0":{"name":"telegram-notify-mcp","version":"2.0.0","keywords":["mcp","telegram","notifications","botfather","model-context-protocol"],"author":{"url":"https://digitalhand.site","name":"Ehsan Eskandari pour","email":"e.eskandaripour7@gmail.com"},"license":"MIT","_id":"telegram-notify-mcp@2.0.0","maintainers":[{"name":"internetchk","email":"internetchk@gmail.com"}],"homepage":"https://digitalhand.site","bugs":{"url":"https://digitalhand.site/contact","email":"e.eskandaripour7@gmail.com"},"bin":{"telegram-notify-mcp":"dist/index.js"},"dist":{"shasum":"6904ca3468097fac3cb739386a8ad0f1e2721936","tarball":"https://registry.npmjs.org/telegram-notify-mcp/-/telegram-notify-mcp-2.0.0.tgz","fileCount":19,"integrity":"sha512-2befN9HBoNmvgTdy6uRdRVaJUorQzI4GUJCpTn8hjX3c4iES5IRzxOeyZMJBPQhN5cv7cwtZwWcC1vWnm9/wfw==","signatures":[{"sig":"MEUCIQDEd+HHUi/+IrM1JdtceLgyJpcfpq5rJUufSgU+9wZEOAIgbRhCKcEmX+MJdlIxz03VBFlhe2sSwt/0fb/VDi9uDrQ=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":84317},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=20"},"scripts":{"test":"node --import tsx --test tests/telegram.test.ts tests/phase2.test.ts","build":"tsc","start":"node dist/index.js","prepare":"tsc"},"_npmUser":{"name":"internetchk","email":"internetchk@gmail.com"},"_npmVersion":"9.2.0","description":"MCP connector/server that sends Telegram notifications via your own BotFather bot (BYOB), with Phase 2 inbound reply routing to the originating agent.","directories":{},"_nodeVersion":"20.19.2","dependencies":{"zod":"^3.23.8","@modelcontextprotocol/sdk":"^1.18.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.0","typescript":"^5.6.0","@types/node":"^20.14.0"},"_npmOperationalInternal":{"tmp":"tmp/telegram-notify-mcp_2.0.0_1789138838043_0.35369695722373007","host":"s3://npm-registry-packages-npm-production"}},"2.1.0":{"name":"telegram-notify-mcp","version":"2.1.0","keywords":["mcp","telegram","notifications","botfather","model-context-protocol"],"author":{"url":"https://digitalhand.site","name":"Ehsan Eskandari pour","email":"e.eskandaripour7@gmail.com"},"license":"MIT","_id":"telegram-notify-mcp@2.1.0","maintainers":[{"name":"internetchk","email":"internetchk@gmail.com"}],"homepage":"https://digitalhand.site","bugs":{"url":"https://digitalhand.site/contact","email":"e.eskandaripour7@gmail.com"},"bin":{"telegram-notify-mcp":"dist/index.js"},"dist":{"shasum":"1488059bbe988c117e917c90a6f1b9ea7c329ee5","tarball":"https://registry.npmjs.org/telegram-notify-mcp/-/telegram-notify-mcp-2.1.0.tgz","fileCount":19,"integrity":"sha512-uXJ6vKbBKDq2WPMu1H3Kw0DlnnjDEQIigl3trjr3QXZfELEnPfbJIvXmhx4Mbec8TRX/4GXqXRWAb1teBpYt0g==","signatures":[{"sig":"MEUCIQDHXwm7AvDYlHOjO848E5BC0cfBA/3nx0LfLbzfQGW0fAIgU3EPACaiMq5JoLqa//bzZL1LHCsspvCUCZ63WmrR98I=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":112078},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=20"},"scripts":{"test":"node --import tsx --test tests/telegram.test.ts tests/phase2.test.ts","build":"tsc","start":"node dist/index.js","prepare":"tsc"},"_npmUser":{"name":"internetchk","email":"internetchk@gmail.com"},"_npmVersion":"9.2.0","description":"MCP connector/server that sends Telegram notifications via your own BotFather bot (BYOB), with Phase 2 inbound reply routing and inline approval buttons.","directories":{},"_nodeVersion":"20.19.2","dependencies":{"zod":"^3.23.8","@modelcontextprotocol/sdk":"^1.18.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.0","typescript":"^5.6.0","@types/node":"^20.14.0"},"_npmOperationalInternal":{"tmp":"tmp/telegram-notify-mcp_2.1.0_1789275264728_0.2484480812357599","host":"s3://npm-registry-packages-npm-production"}},"2.2.0":{"name":"telegram-notify-mcp","version":"2.2.0","keywords":["mcp","telegram","notifications","botfather","model-context-protocol"],"author":{"url":"https://digitalhand.site","name":"Ehsan Eskandari pour","email":"e.eskandaripour7@gmail.com"},"license":"MIT","_id":"telegram-notify-mcp@2.2.0","maintainers":[{"name":"internetchk","email":"internetchk@gmail.com"}],"homepage":"https://digitalhand.site","bugs":{"url":"https://digitalhand.site/contact","email":"e.eskandaripour7@gmail.com"},"bin":{"telegram-notify-mcp":"dist/index.js"},"dist":{"shasum":"9ab2f390b12cd77ecd036907e99c38c9c0a6b167","tarball":"https://registry.npmjs.org/telegram-notify-mcp/-/telegram-notify-mcp-2.2.0.tgz","fileCount":19,"integrity":"sha512-pbAYa39bc/S2EGNy2qOfjw//jm4YPcOd8cuyF+TKVUOr+aLFkS7nXVsNGWavp530fdLQEBDHR1dhhZlI+WC+FQ==","signatures":[{"sig":"MEYCIQC5VWGCqS1yilLnCzsXjMcMQN6ZPXczkH0PVttGkPfJ7QIhAOEqU5vvf280WC6CBPWpcGNUwcU8/zvt0yHgRzWqh1ud","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":119194},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=20"},"scripts":{"test":"node --import tsx --test tests/telegram.test.ts tests/phase2.test.ts","build":"tsc","start":"node dist/index.js","prepare":"tsc"},"_npmUser":{"name":"internetchk","email":"internetchk@gmail.com"},"_npmVersion":"9.2.0","description":"MCP connector/server that sends Telegram notifications via your own BotFather bot (BYOB), with Phase 2 inbound reply routing and inline approval buttons.","directories":{},"_nodeVersion":"20.19.2","dependencies":{"zod":"^3.23.8","@modelcontextprotocol/sdk":"^1.18.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.0","typescript":"^5.6.0","@types/node":"^20.14.0"},"_npmOperationalInternal":{"tmp":"tmp/telegram-notify-mcp_2.2.0_1789331707419_0.3867790774110347","host":"s3://npm-registry-packages-npm-production"}},"2.2.1":{"name":"telegram-notify-mcp","version":"2.2.1","description":"MCP connector/server that sends Telegram notifications via your own BotFather bot (BYOB), with Phase 2 inbound reply routing and inline approval buttons.","type":"module","main":"dist/index.js","bin":{"telegram-notify-mcp":"dist/index.js"},"scripts":{"build":"tsc","start":"node dist/index.js","test":"node --import tsx --test tests/telegram.test.ts tests/phase2.test.ts","prepare":"tsc"},"engines":{"node":">=20"},"keywords":["mcp","telegram","notifications","botfather","model-context-protocol"],"author":{"name":"Ehsan Eskandari pour","email":"e.eskandaripour7@gmail.com","url":"https://digitalhand.site"},"homepage":"https://digitalhand.site","bugs":{"url":"https://digitalhand.site/contact","email":"e.eskandaripour7@gmail.com"},"license":"MIT","dependencies":{"@modelcontextprotocol/sdk":"^1.18.0","zod":"^3.23.8"},"devDependencies":{"@types/node":"^20.14.0","tsx":"^4.19.0","typescript":"^5.6.0"},"types":"./dist/index.d.ts","_id":"telegram-notify-mcp@2.2.1","_nodeVersion":"20.19.2","_npmVersion":"9.2.0","dist":{"integrity":"sha512-H40VPcGJETBk/9uxbF7g40NX+tTAS7PT25NUefF7ht6pKeAYGM8FxI7crSYwnIPb3xMbLedMyCElEQ0ymCrj1Q==","shasum":"87ce63b4c93394e8653ebb662a7007428492c6d0","tarball":"https://registry.npmjs.org/telegram-notify-mcp/-/telegram-notify-mcp-2.2.1.tgz","fileCount":22,"unpackedSize":119576,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCiSd81miJjOqo+bBbDGsbQY+72EnwZ4mnMgOIXKxZPuwIhAJTXOT2H9Ob4Ne/V5JVHJOqvj8ryoVZYigPP8LzmxF29"}]},"_npmUser":{"name":"internetchk","email":"internetchk@gmail.com"},"directories":{},"maintainers":[{"name":"internetchk","email":"internetchk@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/telegram-notify-mcp_2.2.1_1789394663799_0.7305305784153704"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-06T21:09:28.141Z","modified":"2026-09-14T14:04:24.153Z","1.0.0":"2026-09-06T21:09:28.409Z","2.0.0":"2026-09-11T15:00:38.179Z","2.1.0":"2026-09-13T04:54:24.869Z","2.2.0":"2026-09-13T20:35:07.552Z","2.2.1":"2026-09-14T14:04:23.961Z"},"bugs":{"url":"https://digitalhand.site/contact","email":"e.eskandaripour7@gmail.com"},"author":{"name":"Ehsan Eskandari pour","email":"e.eskandaripour7@gmail.com","url":"https://digitalhand.site"},"license":"MIT","homepage":"https://digitalhand.site","keywords":["mcp","telegram","notifications","botfather","model-context-protocol"],"description":"MCP connector/server that sends Telegram notifications via your own BotFather bot (BYOB), with Phase 2 inbound reply routing and inline approval buttons.","maintainers":[{"name":"internetchk","email":"internetchk@gmail.com"}],"readme":"# telegram-notify-mcp\n\n**MCP connector / server** (stdio) that talks to the [Telegram Bot HTTP API](https://core.telegram.org/bots/api) using **your own** bot from [@BotFather](https://t.me/BotFather) (BYOB — bring your own bot).\n\nThis package is **not** a chat persona or hosted SaaS. It is a local Model Context Protocol server you run under Cursor, Grok Bot, or any MCP host. No secrets ship in the repo; configuration is environment-only.\n\n**Publisher:** Ehsan Eskandari pour  \n**Version:** 2.2.0 (Phase 2 + inline approval buttons — Accept / Decline / Custom)\n\n## How it works\n\n1. You create a Telegram bot with BotFather and receive an HTTP API token.\n2. You run this MCP server with `TELEGRAM_BOT_TOKEN` (and optionally `TELEGRAM_CHAT_ID`) in the process environment.\n3. Your MCP host lists the tools and can call them over stdio.\n4. **Outbound:** notify tools send messages, append an agent footer, and persist `message_id → source_agent_id` mappings locally.\n5. **Inbound (Phase 2):** a host poller calls `telegram_poll_inbound` → `telegram_list_pending_commands` → delivers via the host’s **SendToAgent** (or equivalent) → `telegram_ack_command`.\n\nMCP alone cannot wake agents asynchronously (stdio is pull-only). See [ARCHITECTURE-PHASE2.md](./ARCHITECTURE-PHASE2.md).\n\n## Tools\n\n### Phase 1 (still available)\n\n| Tool | Purpose |\n|------|---------|\n| `telegram_get_me` | `getMe` — verify token; return bot id/username |\n| `telegram_send_message` | Send text (`chat_id` optional if env default set). Optional `source_agent_id` / `source_agent_name` for footer + mapping |\n| `telegram_get_updates` | List recent updates to discover `chat_id` after `/start` (does **not** enqueue commands) |\n\n### Phase 2 — notify + inbound queue\n\n| Tool | Purpose |\n|------|---------|\n| `telegram_notify` | Completion notification (`title?` + `body`). **Requires** `source_agent_id`; optional `source_agent_name`. Appends footer; persists mapping. Optional opt-in approval buttons (`approval_buttons`, `accept_command`, `decline_command`) |\n| `telegram_poll_inbound` | `getUpdates` + allowlist + route into pending queue; returns summary counts |\n| `telegram_list_pending_commands` | List pending commands (optional `source_agent_id` filter) |\n| `telegram_ack_command` | Ack/delete by `command_id` after host delivery |\n\n### Inbound routing rules\n\n1. Only messages from allowlisted chats (`TELEGRAM_CHAT_ALLOWLIST` or `TELEGRAM_CHAT_ID`) are considered.\n2. If the message is a **Telegram reply** to a mapped outbound `message_id`, enqueue for that `source_agent_id`.\n3. Else if text starts with `/to <agent_id> <command…>`, enqueue for that agent (fallback).\n4. **Approval callbacks** (`callback_query`): Accept → enqueue `accept_command`; Decline → enqueue `decline_command`; Custom → bot sends a ForceReply prompt mapped to the same agent (next reply becomes a normal pending command).\n5. Else **ignore** (counted as `ignored_unroutable` in the poll result). No shell execution inside MCP.\n\n### Optional approval buttons (2.1, opt-in)\n\nPass `approval_buttons: true` on `telegram_notify` or on `telegram_send_message` (with `source_agent_id`) to attach an inline keyboard. **Default is off** — plain notify / reply mapping only.\n\n- **Accept** / **Decline** — enqueue `accept_command` / `decline_command` for the originating agent (same pending queue as text replies).\n- **Custom** — clears the keyboard and opens a Telegram **ForceReply** on that same bot message so you can type a free-text reply (routed to the same agent).\n\nCaller-defined roles/labels (optional):\n\n| Param | Purpose |\n|-------|---------|\n| `accept_command` / `decline_command` | Text enqueued when Accept / Decline is pressed |\n| `accept_label` / `decline_label` / `custom_label` | Button titles shown in Telegram |\n| `custom_placeholder` | Placeholder in the reply field after Custom |\n\nDefaults: labels `Accept` / `Decline` / `Custom message`; commands `\"Accept\"` / `\"Decline\"`. Pending queue format is unchanged — host bridge still list → deliver → ack.\n\n## Host poller responsibilities (M3 bridge)\n\nA host **routine / skill / daemon** must periodically:\n\n1. Call `telegram_poll_inbound` (fills the queue; advances update offset).\n2. Call `telegram_list_pending_commands`.\n3. For each command, deliver `text` to the agent identified by `source_agent_id` via **SendToAgent** (or the host’s equivalent channel).\n4. Call `telegram_ack_command` with that command’s `id` after successful delivery.\n\nWithout this loop, pending commands sit on disk and no agent wakes. See [`skill-snippet.md`](./skill-snippet.md) for a copy-paste host-bridge sketch.\n\n## BotFather setup\n\n1. Open Telegram and chat with [@BotFather](https://t.me/BotFather).\n2. Send `/newbot`, choose a display name and a username ending in `bot`.\n3. Copy the **HTTP API token** BotFather gives you. This is `TELEGRAM_BOT_TOKEN`.\n4. (Optional) Leave privacy defaults; for personal notify bots this is fine.\n\n**Never commit the token.** Put it only in MCP env / your secret store.\n\n## How to get `chat_id`\n\n1. Start this MCP server with `TELEGRAM_BOT_TOKEN` set (no `TELEGRAM_CHAT_ID` yet).\n2. In Telegram, open your bot and tap **Start** (or send `/start`).\n3. Call tool `telegram_get_updates` (optional `limit`).\n4. Read `discovered_chats[].chat_id` from the result.\n5. Set `TELEGRAM_CHAT_ID` to that value so send/notify can omit `chat_id`, and inbound allowlisting works.\n\nPrivate chats use a numeric id (e.g. `123456789`). Groups/channels may use negative ids.\n\n## Install\n\nRequires **Node.js 20+**.\n\n```bash\nnpm install telegram-notify-mcp\n# or from a release tarball / local path (GitHub repo not published yet):\ncd /absolute/path/to/telegram-notify-mcp\nnpm install\nnpm run build\nnpm test\n```\n\nEnvironment variables (see [`.env.example`](./.env.example)):\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `TELEGRAM_BOT_TOKEN` | Yes (for tool calls) | BotFather HTTP API token |\n| `TELEGRAM_CHAT_ID` | No | Default chat for send/notify; also used as inbound allowlist |\n| `TELEGRAM_CHAT_ALLOWLIST` | No | Comma-separated chat ids allowed for inbound commands |\n| `TELEGRAM_NOTIFY_DATA_DIR` | No | Directory for mapping + pending JSON (default `./.telegram-notify-data`) |\n\nThe process starts even if `TELEGRAM_BOT_TOKEN` is missing (so the host can list tools); tool calls then return a clear error until the token is set.\n\nLocal data under `.telegram-notify-data/` is **gitignored** and **not** included in the npm `files` list.\n\n## Add MCP in Cursor / Grok Bot\n\nUse a **local** command + env. Example with a built clone:\n\n```json\n{\n  \"mcpServers\": {\n    \"telegram-notify\": {\n      \"command\": \"node\",\n      \"args\": [\n        \"/absolute/path/to/telegram-notify-mcp/dist/index.js\"\n      ],\n      \"env\": {\n        \"TELEGRAM_BOT_TOKEN\": \"123456:ABC-DEF...\",\n        \"TELEGRAM_CHAT_ID\": \"123456789\"\n      }\n    }\n  }\n}\n```\n\nOr via `npx` after publishing / linking:\n\n```json\n{\n  \"mcpServers\": {\n    \"telegram-notify\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"--yes\",\n        \"telegram-notify-mcp\"\n      ],\n      \"env\": {\n        \"TELEGRAM_BOT_TOKEN\": \"123456:ABC-DEF...\",\n        \"TELEGRAM_CHAT_ID\": \"123456789\"\n      }\n    }\n  }\n}\n```\n\nIf your host UI has **Add MCP** fields instead of raw JSON:\n\n- **command:** `node`\n- **args:** `/absolute/path/to/telegram-notify-mcp/dist/index.js`\n- **env:** `TELEGRAM_BOT_TOKEN`, optional `TELEGRAM_CHAT_ID` / `TELEGRAM_CHAT_ALLOWLIST` / `TELEGRAM_NOTIFY_DATA_DIR`\n\n## Example notify flow (Phase 2)\n\n1. Configure token (+ default chat id) as above; reload MCP.\n2. `telegram_get_me` → confirm username.\n3. When a task finishes, call `telegram_notify` with **required** `source_agent_id`:\n\n```json\n{\n  \"title\": \"Deploy finished\",\n  \"body\": \"staging is live; smoke tests passed.\",\n  \"source_agent_id\": \"agent-deploy-1\",\n  \"source_agent_name\": \"Deploy helper\",\n  \"accept_command\": \"proceed with smoke tests\",\n  \"decline_command\": \"abort deploy follow-up\"\n}\n```\n\nTelegram shows something like:\n\n```text\n✅ Deploy finished\n\nstaging is live; smoke tests passed.\n\n— from agent Deploy helper\nReply to this message to continue with this agent.\n```\n\n4. User taps **Accept** / **Decline** / **Custom**, or **replies** to that message (or sends `/to agent-deploy-1 …`).\n5. Host poller: `telegram_poll_inbound` → list → SendToAgent → `telegram_ack_command`.\n\n## Security notes\n\n- Token grants full control of the bot — treat it like a password. **Do not log tokens.**\n- This server does **not** execute shell or arbitrary code from Telegram text; it only enqueues text/metadata for the host.\n- Inbound commands are restricted to the chat allowlist.\n- Configuration is **env-only** for the published server. Do not commit tokens or chat ids.\n- Mapping/pending data stays local; do not publish `.telegram-notify-data` in releases.\n\n## Contact\n\n- **Author:** Ehsan Eskandari pour\n- **Email:** e.eskandaripour7@gmail.com\n- **Website:** https://digitalhand.site\n- **Source:** GitHub repo is not published yet — install from the release tarball or a local path (not `git clone` of a public URL).\n\n## License\n\nMIT — see [LICENSE](./LICENSE).\n\n## Roadmap\n\nMilestones and remaining work: [ROADMAP.md](./ROADMAP.md). Architecture detail: [ARCHITECTURE-PHASE2.md](./ARCHITECTURE-PHASE2.md).\n","readmeFilename":"README.md"}