{"_id":"@benjapieres/mcp-telegram-listener","_rev":"8-532949054fb38b7151ee64724febbf2d","name":"@benjapieres/mcp-telegram-listener","dist-tags":{"latest":"2.0.0"},"versions":{"1.0.0":{"name":"@benjapieres/mcp-telegram-listener","version":"1.0.0","keywords":["mcp","telegram","bot","model-context-protocol"],"license":"MIT","_id":"@benjapieres/mcp-telegram-listener@1.0.0","maintainers":[{"name":"benjapieres","email":"bpieres@gmail.com"}],"bin":{"mcp-telegram-listener":"dist/index.js"},"dist":{"shasum":"61cfc790b0d3e659b561b0507fcaa115841cad4a","tarball":"https://registry.npmjs.org/@benjapieres/mcp-telegram-listener/-/mcp-telegram-listener-1.0.0.tgz","fileCount":3,"integrity":"sha512-DiDQjNUKodBMICOF+eDEefg0EhdXX8I0ZffwL+v+zb4ecxZN1HikwaSgJMUBWPZdRxrxEnmDqyc6PVJH4HNS6Q==","signatures":[{"sig":"MEUCIG1rh9Z75aMQhORVtdSx3o2tYkhcaSP1vHK2/PuF4y6pAiEAlE3GFMR5mELm09OxkJeiosUJBpSwifndx++HW2SqQjk=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":5144},"type":"module","scripts":{"build":"tsc","start":"node dist/index.js","prepublishOnly":"npm run build"},"_npmUser":{"name":"benjapieres","email":"bpieres@gmail.com"},"_npmVersion":"11.6.0","description":"Minimal MCP server to listen and respond to Telegram messages","directories":{},"_nodeVersion":"24.7.0","dependencies":{"grammy":"^1.35.0","@modelcontextprotocol/sdk":"^1.12.1"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.7.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp-telegram-listener_1.0.0_1773235859679_0.5068336791353851","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@benjapieres/mcp-telegram-listener","version":"1.1.0","keywords":["mcp","telegram","bot","model-context-protocol"],"license":"MIT","_id":"@benjapieres/mcp-telegram-listener@1.1.0","maintainers":[{"name":"benjapieres","email":"bpieres@gmail.com"}],"bin":{"mcp-telegram-listener":"dist/index.js"},"dist":{"shasum":"1626498571486e32ee3932d9b8edb4f4f579458d","tarball":"https://registry.npmjs.org/@benjapieres/mcp-telegram-listener/-/mcp-telegram-listener-1.1.0.tgz","fileCount":4,"integrity":"sha512-rCkUIzAr5iTGdqrZe6chWdzkQT36rnCPxdMJh24kmruCGshuUqZSMN4uSOqTbdTlBNAEcdFcVE7ogMJLJkTjVg==","signatures":[{"sig":"MEUCIQCSkCOiXHea8RtyWUZ12Tt6smHDQuv08iLK3JlK10ahOgIgeV5I3LB6D7PvukFmyWRb8VogeoGegszorrrGDfG2f10=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":7304},"type":"module","scripts":{"build":"tsc","start":"node dist/index.js","prepublishOnly":"npm run build"},"_npmUser":{"name":"benjapieres","email":"bpieres@gmail.com"},"_npmVersion":"11.6.0","description":"Minimal MCP server to listen and respond to Telegram messages","directories":{},"_nodeVersion":"24.7.0","dependencies":{"grammy":"^1.35.0","@modelcontextprotocol/sdk":"^1.12.1"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.7.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp-telegram-listener_1.1.0_1773235991105_0.9485894917106785","host":"s3://npm-registry-packages-npm-production"}},"1.2.0":{"name":"@benjapieres/mcp-telegram-listener","version":"1.2.0","keywords":["mcp","telegram","bot","model-context-protocol"],"license":"MIT","_id":"@benjapieres/mcp-telegram-listener@1.2.0","maintainers":[{"name":"benjapieres","email":"bpieres@gmail.com"}],"bin":{"mcp-telegram-listener":"dist/index.js"},"dist":{"shasum":"147b3e8542f755fe6ed8984ada8ef87cff8b79eb","tarball":"https://registry.npmjs.org/@benjapieres/mcp-telegram-listener/-/mcp-telegram-listener-1.2.0.tgz","fileCount":4,"integrity":"sha512-ZiPmWAFrg2IxG/bV5LSfEh4dzAGBJhLA6MXnoGwHwxTqiLsp+zTtGFgTvZ6Oum4ENJBiRg9GA9v26FS5xVLslg==","signatures":[{"sig":"MEUCIHs9LetlZaI5x8et9G8KG3LScONnJ/ncshs9mIbQ6jy3AiEA65+iUx+DHzqLoNW0HMycNEKx6hrdlUpNA76hdl8P8EA=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":7740},"type":"module","scripts":{"build":"tsc","start":"node dist/index.js","prepublishOnly":"npm run build"},"_npmUser":{"name":"benjapieres","email":"bpieres@gmail.com"},"_npmVersion":"11.6.0","description":"Minimal MCP server to listen and respond to Telegram messages","directories":{},"_nodeVersion":"24.7.0","dependencies":{"grammy":"^1.35.0","@modelcontextprotocol/sdk":"^1.12.1"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.7.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp-telegram-listener_1.2.0_1773236929961_0.10794747592080634","host":"s3://npm-registry-packages-npm-production"}},"1.3.0":{"name":"@benjapieres/mcp-telegram-listener","version":"1.3.0","keywords":["mcp","telegram","bot","model-context-protocol"],"license":"MIT","_id":"@benjapieres/mcp-telegram-listener@1.3.0","maintainers":[{"name":"benjapieres","email":"bpieres@gmail.com"}],"bin":{"mcp-telegram-listener":"dist/index.js"},"dist":{"shasum":"8361bc97f1e6dc04a028fa7680995f76492ba679","tarball":"https://registry.npmjs.org/@benjapieres/mcp-telegram-listener/-/mcp-telegram-listener-1.3.0.tgz","fileCount":4,"integrity":"sha512-akbrG5Rf2qMoPtjdnjZXjIZrdtNnQn2tF/gsgteeJ7tHUdKohz5vhJmCM8t+cIOKQSb0VT6B1KlE3B+1jdh5eg==","signatures":[{"sig":"MEYCIQCrpFqJaG22R9At1/MsJhYgks4ZvLyByQUz+ymPPpxu6AIhAMsigGVCYA8ByzqTfprp5d0EMkMXTAKlPjk8YEoYdr7k","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":8380},"type":"module","scripts":{"build":"tsc","start":"node dist/index.js","prepublishOnly":"npm run build"},"_npmUser":{"name":"benjapieres","email":"bpieres@gmail.com"},"_npmVersion":"11.6.0","description":"Minimal MCP server to listen and respond to Telegram messages","directories":{},"_nodeVersion":"24.7.0","dependencies":{"grammy":"^1.35.0","@modelcontextprotocol/sdk":"^1.12.1"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.7.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp-telegram-listener_1.3.0_1773238731945_0.9137002773717087","host":"s3://npm-registry-packages-npm-production"}},"1.4.0":{"name":"@benjapieres/mcp-telegram-listener","version":"1.4.0","keywords":["mcp","telegram","bot","model-context-protocol"],"license":"MIT","_id":"@benjapieres/mcp-telegram-listener@1.4.0","maintainers":[{"name":"benjapieres","email":"bpieres@gmail.com"}],"bin":{"mcp-telegram-listener":"dist/index.js"},"dist":{"shasum":"8fc7dd4f33a960df9688e6524844aac6fb332912","tarball":"https://registry.npmjs.org/@benjapieres/mcp-telegram-listener/-/mcp-telegram-listener-1.4.0.tgz","fileCount":4,"integrity":"sha512-NMx9c2UUBo+Qbg23Hb8CYW6R5z7j0ezapEokfOjYGkc9U22HDG3yNbefQx3ehw94jIMCvt9ZUVEgroiK9uUqqw==","signatures":[{"sig":"MEYCIQCCBAkRw0f4j8YmM9WJ/HXuessh+JgcrAt/dHmH1LEa6QIhANjs7TT5L9Rw1S/Geju7SzM0kqM9yc2BNMvQNwe9cC9Z","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":10238},"type":"module","scripts":{"build":"tsc","start":"node dist/index.js","prepublishOnly":"npm run build"},"_npmUser":{"name":"benjapieres","email":"bpieres@gmail.com"},"_npmVersion":"11.6.0","description":"Minimal MCP server to listen and respond to Telegram messages","directories":{},"_nodeVersion":"24.7.0","dependencies":{"grammy":"^1.35.0","@modelcontextprotocol/sdk":"^1.12.1"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.7.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp-telegram-listener_1.4.0_1773524364486_0.9257715784077565","host":"s3://npm-registry-packages-npm-production"}},"1.5.0":{"name":"@benjapieres/mcp-telegram-listener","version":"1.5.0","keywords":["mcp","telegram","bot","model-context-protocol"],"license":"MIT","_id":"@benjapieres/mcp-telegram-listener@1.5.0","maintainers":[{"name":"benjapieres","email":"bpieres@gmail.com"}],"bin":{"mcp-telegram-listener":"dist/index.js"},"dist":{"shasum":"ffb3f5ffb78aee41947eb5dcc8a3be79ce2224b3","tarball":"https://registry.npmjs.org/@benjapieres/mcp-telegram-listener/-/mcp-telegram-listener-1.5.0.tgz","fileCount":4,"integrity":"sha512-5EyspKaFbcDI9usy4X6YJUEcKuY+ErzHYXEJs8X63EuTNr9kafPM/4kief+tv9lSZABReeefFyKLLUAZE2Dv3A==","signatures":[{"sig":"MEYCIQDGNex8XcgWuMXkIguKdz2YXQqC7hWnEizw6/xGwYGLjgIhAJKibmPjTowbHuHBssXNCyRAl8jdfGiEYVXtHKGrQwh0","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":10836},"type":"module","scripts":{"build":"tsc","start":"node dist/index.js","prepublishOnly":"npm run build"},"_npmUser":{"name":"benjapieres","email":"bpieres@gmail.com"},"_npmVersion":"11.6.0","description":"Minimal MCP server to listen and respond to Telegram messages","directories":{},"_nodeVersion":"24.7.0","dependencies":{"grammy":"^1.35.0","@modelcontextprotocol/sdk":"^1.12.1"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.7.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp-telegram-listener_1.5.0_1773524445264_0.03496973471415865","host":"s3://npm-registry-packages-npm-production"}},"1.6.0":{"name":"@benjapieres/mcp-telegram-listener","version":"1.6.0","keywords":["mcp","telegram","bot","model-context-protocol"],"license":"MIT","_id":"@benjapieres/mcp-telegram-listener@1.6.0","maintainers":[{"name":"benjapieres","email":"bpieres@gmail.com"}],"bin":{"mcp-telegram-listener":"dist/index.js"},"dist":{"shasum":"3159e34063e2cf4f0acb627d67592077a390bcbb","tarball":"https://registry.npmjs.org/@benjapieres/mcp-telegram-listener/-/mcp-telegram-listener-1.6.0.tgz","fileCount":4,"integrity":"sha512-D7SZBRNcHz2Z/DIx1K6Scu+P6WG0Mv9zAX8p7jIT5qwugYrCkuxb5Bl+SV+lUW001hSQqk5g07vRYVdV0GnvUA==","signatures":[{"sig":"MEUCIQCQzeSeSPvNgfxKePkIWHJKRd5pukGBcuE7fadiL8enGwIgIfFATUynVA4KpPBlab/sFAGSu21ugZ22QqR63Cx+RtM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":12080},"type":"module","scripts":{"build":"tsc","start":"node dist/index.js","prepublishOnly":"npm run build"},"_npmUser":{"name":"benjapieres","email":"bpieres@gmail.com"},"_npmVersion":"11.6.0","description":"Minimal MCP server to listen and respond to Telegram messages","directories":{},"_nodeVersion":"24.7.0","dependencies":{"grammy":"^1.35.0","@modelcontextprotocol/sdk":"^1.12.1"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.7.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp-telegram-listener_1.6.0_1773527884008_0.4363856546700955","host":"s3://npm-registry-packages-npm-production"}},"2.0.0":{"name":"@benjapieres/mcp-telegram-listener","version":"2.0.0","description":"Minimal MCP server to listen and respond to Telegram messages","type":"module","bin":{"mcp-telegram-listener":"dist/index.js"},"scripts":{"build":"tsc","prepublishOnly":"npm run build","start":"node dist/index.js"},"keywords":["mcp","telegram","bot","model-context-protocol"],"license":"MIT","dependencies":{"@modelcontextprotocol/sdk":"^1.12.1","grammy":"^1.35.0","zod":"^3.24.0"},"devDependencies":{"typescript":"^5.7.0","@types/node":"^22.0.0"},"_id":"@benjapieres/mcp-telegram-listener@2.0.0","_nodeVersion":"24.7.0","_npmVersion":"11.6.0","dist":{"integrity":"sha512-PrEo0EJ/aXphWiAJ7wLlUpC/hyZQMZbB/tEskNDmkCDH2f2iTvRKjpCxE/QAneqbVuCH8/WD+5MSwPS9rzd7Iw==","shasum":"a2e85a021f50cf980eb8f98957684ee68fdef29d","tarball":"https://registry.npmjs.org/@benjapieres/mcp-telegram-listener/-/mcp-telegram-listener-2.0.0.tgz","fileCount":4,"unpackedSize":16362,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIA6Q7QRXPmthzQKpgrQK44hGKh0zw1Q473SXrfSZnWyWAiEAg3q1elTpvH0Xv/AxgrbQc1p9P2seCWbMhgfI9DP1gYo="}]},"_npmUser":{"name":"benjapieres","email":"bpieres@gmail.com"},"directories":{},"maintainers":[{"name":"benjapieres","email":"bpieres@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-telegram-listener_2.0.0_1773547335734_0.407701491830297"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-11T13:30:59.604Z","modified":"2026-03-15T04:02:15.993Z","1.0.0":"2026-03-11T13:30:59.818Z","1.1.0":"2026-03-11T13:33:11.266Z","1.2.0":"2026-03-11T13:48:50.098Z","1.3.0":"2026-03-11T14:18:52.092Z","1.4.0":"2026-03-14T21:39:24.618Z","1.5.0":"2026-03-14T21:40:45.472Z","1.6.0":"2026-03-14T22:38:04.165Z","2.0.0":"2026-03-15T04:02:15.877Z"},"license":"MIT","keywords":["mcp","telegram","bot","model-context-protocol"],"description":"Minimal MCP server to listen and respond to Telegram messages","maintainers":[{"name":"benjapieres","email":"bpieres@gmail.com"}],"readme":"# @benjapieres/mcp-telegram-listener\n\nMinimal MCP server that listens to Telegram messages and exposes them to AI agents. No third-party AI sampling, no magic — you control what happens with each message.\n\n## Setup\n\n### 1. Create a Telegram bot\n\nTalk to [@BotFather](https://t.me/BotFather) and get your bot token.\n\n### 2. Get your chat/group ID\n\nAdd the bot to your group, send a message, and check the logs — the chat ID will appear there. Group IDs are negative numbers (e.g. `-1001234567890`).\n\n### 3. Configure your MCP client\n\nAdd this to your Claude Desktop or Claude Code MCP config:\n\n```json\n{\n  \"mcpServers\": {\n    \"telegram\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@benjapieres/mcp-telegram-listener\"],\n      \"env\": {\n        \"TELEGRAM_BOT_TOKEN\": \"your_bot_token\",\n        \"ALLOWED_CHAT_IDS\": \"-1001234567890,-1009876543210\",\n        \"REQUIRE_MENTION\": \"false\",\n        \"QUEUE_PATH\": \"/path/to/your/workspace/.meta/telegram-queue.json\"\n      }\n    }\n  }\n}\n```\n\n**Multiple bots** (e.g. separate bots for different groups):\n\n```json\n{\n  \"mcpServers\": {\n    \"telegram-pm\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@benjapieres/mcp-telegram-listener\"],\n      \"env\": {\n        \"TELEGRAM_BOT_TOKEN\": \"pm_bot_token\",\n        \"ALLOWED_CHAT_IDS\": \"-1001234567890\",\n        \"REQUIRE_MENTION\": \"false\",\n        \"QUEUE_PATH\": \"/workspace/.meta/telegram-pm-queue.json\"\n      }\n    },\n    \"telegram-leads\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@benjapieres/mcp-telegram-listener\"],\n      \"env\": {\n        \"TELEGRAM_BOT_TOKEN\": \"leads_bot_token\",\n        \"ALLOWED_CHAT_IDS\": \"-1009876543210\",\n        \"REQUIRE_MENTION\": \"false\",\n        \"QUEUE_PATH\": \"/workspace/.meta/telegram-leads-queue.json\"\n      }\n    }\n  }\n}\n```\n\n## Environment variables\n\n| Variable | Required | Default | Description |\n|---|---|---|---|\n| `TELEGRAM_BOT_TOKEN` | Yes | — | Bot token from @BotFather |\n| `ALLOWED_CHAT_IDS` | No | (all) | Comma-separated chat/group IDs. Empty = accept all |\n| `REQUIRE_MENTION` | No | `true` | Set to `false` to receive all group messages without needing a bot mention |\n| `QUEUE_PATH` | No | `./telegram-queue.json` | Absolute path for queue persistence across restarts |\n\n## Tools\n\n| Tool | Description |\n|---|---|\n| `get_messages` | Returns pending messages and removes them from the queue |\n| `peek_messages` | Shows how many messages are queued without consuming them |\n| `send_message` | Sends a text message to a Telegram chat |\n| `get_bot_info` | Returns bot info and current configuration — useful to verify setup |\n\n### get_messages\n\nReturns pending messages with sender info, username, chat ID, topic ID, reply_to ID, and timestamp.\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `chat_id` | string | No | Filter messages from a specific chat. Messages from other chats stay in queue. |\n| `max_messages` | number | No | Maximum messages to return (1–100). Default: all pending. |\n| `format` | string | No | `\"text\"` (default, human-readable) or `\"json\"` (structured array). |\n\n### peek_messages\n\nReturns the current queue size without consuming messages. Also starts polling if not already running.\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `chat_id` | string | No | Count only messages from a specific chat. |\n\n### send_message\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `text` | string | Yes | Message text to send |\n| `chat_id` | string | No | Target chat ID. Defaults to first `ALLOWED_CHAT_IDS` |\n| `topic_id` | number | No | Topic/thread ID for forum supergroups (`message_thread_id`) |\n| `reply_to_message_id` | number | No | Reply to a specific message within the chat |\n| `parse_mode` | string | No | `HTML`, `Markdown`, or `MarkdownV2` |\n\n### get_bot_info\n\nNo parameters. Returns bot id, username, name, and current config (allowed chats, require_mention, queue path).\n\n## How it works\n\n```\nTelegram  ←→  Bot (polling)  ←→  MCP server (stdio)  ←→  AI agent\n```\n\n- Polling starts lazily on the first `get_messages` or `peek_messages` call — not at initialization. This avoids token conflicts when multiple processes use the same bot.\n- Incoming messages are stored in a FIFO queue (max 200)\n- The agent reads messages on demand via `get_messages`\n- Queue is persisted to disk and survives process restarts\n- Everything runs locally — no external servers needed\n\n## License\n\nMIT\n","readmeFilename":"README.md"}