{"_id":"@tonresistor/telegram-mcp","name":"@tonresistor/telegram-mcp","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@tonresistor/telegram-mcp","version":"1.0.0","description":"Production-ready MCP Server for Telegram Bot API - 162 methods with token-optimized meta mode","type":"module","main":"build/index.js","bin":{"telegram-mcp":"build/index.js"},"scripts":{"build":"tsc","start":"node build/index.js","start:meta":"node build/index-meta.js","dev":"tsc --watch","clean":"rm -rf build","rebuild":"npm run clean && npm run build","prepublishOnly":"npm run rebuild && npm test","test":"vitest run","test:watch":"vitest","test:coverage":"vitest run --coverage"},"repository":{"type":"git","url":"git+https://github.com/TONresistor/telegram-mcp.git"},"bugs":{"url":"https://github.com/TONresistor/telegram-mcp/issues"},"homepage":"https://github.com/TONresistor/telegram-mcp#readme","dependencies":{"@modelcontextprotocol/sdk":"^1.0.0","prom-client":"^15.1.3","zod":"^3.23.0"},"devDependencies":{"@types/node":"^22.0.0","@vitest/coverage-v8":"^4.0.17","typescript":"^5.7.0","vitest":"^4.0.17"},"engines":{"node":">=18.0.0"},"keywords":["mcp","telegram","bot","model-context-protocol","api","chatbot","messaging","ai-tools"],"author":{"name":"TONresistor"},"license":"MIT","_id":"@tonresistor/telegram-mcp@1.0.0","gitHead":"62972835bb528a380f6bed284bb980d23aa31472","types":"./build/index.d.ts","_nodeVersion":"22.20.0","_npmVersion":"10.9.3","dist":{"integrity":"sha512-+J7EhKuxk6m19K0KMvNdzZu/Hlv27V4DMmXrtGbZRMUtyHZg0FOdf2pH6flA5EQ/gRzLWUH7gFVFuWs9bBUfSg==","shasum":"bf16ef1ff29559d1d13e3f5761a13d3239623151","tarball":"https://registry.npmjs.org/@tonresistor/telegram-mcp/-/telegram-mcp-1.0.0.tgz","fileCount":111,"unpackedSize":734855,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDdj270duF8dWEoPAcBSwJYqBTkoqPgVlej0R2mgY2m9gIhAM3mRob1GiWNpDSw8wER0GaYHRhMSSy+oBCRQ9rHjJt0"}]},"_npmUser":{"name":"tonresistor","email":"stress-frayed-why@duck.com"},"directories":{},"maintainers":[{"name":"tonresistor","email":"stress-frayed-why@duck.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/telegram-mcp_1.0.0_1768299554894_0.09974960592034021"},"_hasShrinkwrap":false}},"time":{"created":"2026-01-13T10:19:14.819Z","1.0.0":"2026-01-13T10:19:15.106Z","modified":"2026-01-13T10:19:15.344Z"},"maintainers":[{"name":"tonresistor","email":"stress-frayed-why@duck.com"}],"description":"Production-ready MCP Server for Telegram Bot API - 162 methods with token-optimized meta mode","homepage":"https://github.com/TONresistor/telegram-mcp#readme","keywords":["mcp","telegram","bot","model-context-protocol","api","chatbot","messaging","ai-tools"],"repository":{"type":"git","url":"git+https://github.com/TONresistor/telegram-mcp.git"},"author":{"name":"TONresistor"},"bugs":{"url":"https://github.com/TONresistor/telegram-mcp/issues"},"license":"MIT","readme":"# Telegram MCP Server\n\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue.svg)](https://www.typescriptlang.org/)\n[![MCP](https://img.shields.io/badge/MCP-1.0-green.svg)](https://modelcontextprotocol.io/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\nProduction-ready MCP server for the complete Telegram Bot API. **162 methods** with token-optimized meta mode (~157 tokens vs ~55,000).\n\n## Highlights\n\n- **Complete API coverage** — All 162 Telegram Bot API methods\n- **Token efficient** — Meta mode reduces context by 99.7%\n- **Production hardened** — Circuit breaker, rate limiting, retries with backoff\n- **Observable** — Prometheus metrics, structured logging, health checks\n- **Type safe** — Full TypeScript with Zod validation\n\n## Quick Start\n\n```bash\nnpm install && npm run build\n```\n\nGet your bot token from [@BotFather](https://t.me/BotFather), then add to your MCP config:\n\n```json\n{\n  \"mcpServers\": {\n    \"telegram\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/build/index-meta.js\"],\n      \"env\": {\n        \"TELEGRAM_BOT_TOKEN\": \"your_token_here\"\n      }\n    }\n  }\n}\n```\n\n## Usage Modes\n\n| Mode | Entry Point | Tools | Best For |\n|------|-------------|-------|----------|\n| **Meta** (recommended) | `index-meta.js` | 2 | Production — minimal token usage |\n| Standard | `index.js` | 161 | Development — direct tool access |\n\n**Meta mode** exposes just 2 tools:\n- `telegram_find` — Search methods by name or category\n- `telegram_call` — Execute any Telegram API method\n\n## Configuration\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `TELEGRAM_BOT_TOKEN` | **required** | Bot token from BotFather |\n| `LOG_LEVEL` | `info` | debug / info / warning / error / critical |\n| `REQUEST_TIMEOUT` | `30000` | Request timeout in ms (5000-120000) |\n| `MAX_RETRIES` | `3` | Retry attempts (0-10) |\n| `RATE_LIMIT_PER_MINUTE` | `30` | Global rate limit (1-60) |\n| `HEALTH_PORT` | — | Enable health endpoints (/health, /metrics) |\n\n## Features\n\n### Resilience\n- **Circuit breaker** — Opens after 5 failures, auto-recovers after 30s\n- **Rate limiting** — Global + per-chat (respects Telegram limits)\n- **Retries** — Exponential backoff with jitter\n\n### Observability\n- **Prometheus metrics** — Request counts, latencies, error rates\n- **Health checks** — Kubernetes-ready readiness/liveness probes\n- **Structured logging** — JSON format with automatic secret redaction\n\n## API Reference\n\nAll 161 Telegram Bot API methods organized by category.\n\n<details>\n<summary><strong>Messages</strong> (23 methods)</summary>\n\n| Method | Description |\n|--------|-------------|\n| `sendMessage` | Send text message |\n| `sendPhoto` | Send photo |\n| `sendVideo` | Send video |\n| `sendAudio` | Send audio file |\n| `sendDocument` | Send document/file |\n| `sendAnimation` | Send GIF animation |\n| `sendVoice` | Send voice message |\n| `sendVideoNote` | Send video note (round video) |\n| `sendLocation` | Send location |\n| `sendVenue` | Send venue/place |\n| `sendContact` | Send phone contact |\n| `sendPoll` | Send poll/survey |\n| `sendDice` | Send animated dice |\n| `sendChatAction` | Send typing indicator |\n| `sendMediaGroup` | Send media album |\n| `sendPaidMedia` | Send paid media |\n| `sendMessageDraft` | Stream partial message (AI) |\n| `forwardMessage` | Forward message |\n| `forwardMessages` | Forward multiple messages |\n| `copyMessage` | Copy message |\n| `copyMessages` | Copy multiple messages |\n| `sendSticker` | Send sticker |\n| `sendChecklist` | Send checklist (business) |\n\n</details>\n\n<details>\n<summary><strong>Chat Management</strong> (30 methods)</summary>\n\n| Method | Description |\n|--------|-------------|\n| `getChat` | Get chat info |\n| `getChatMember` | Get member info |\n| `getChatMemberCount` | Get member count |\n| `getChatAdministrators` | List administrators |\n| `banChatMember` | Ban user |\n| `unbanChatMember` | Unban user |\n| `restrictChatMember` | Restrict user |\n| `promoteChatMember` | Promote to admin |\n| `setChatAdministratorCustomTitle` | Set admin title |\n| `setChatPermissions` | Set default permissions |\n| `setChatTitle` | Set chat title |\n| `setChatDescription` | Set chat description |\n| `setChatPhoto` | Set chat photo |\n| `deleteChatPhoto` | Delete chat photo |\n| `pinChatMessage` | Pin message |\n| `unpinChatMessage` | Unpin message |\n| `unpinAllChatMessages` | Unpin all messages |\n| `leaveChat` | Leave chat |\n| `exportChatInviteLink` | Generate invite link |\n| `createChatInviteLink` | Create invite link |\n| `editChatInviteLink` | Edit invite link |\n| `revokeChatInviteLink` | Revoke invite link |\n| `approveChatJoinRequest` | Approve join request |\n| `declineChatJoinRequest` | Decline join request |\n| `banChatSenderChat` | Ban channel |\n| `unbanChatSenderChat` | Unban channel |\n| `setChatStickerSet` | Set sticker set |\n| `deleteChatStickerSet` | Delete sticker set |\n| `createChatSubscriptionInviteLink` | Create subscription link |\n| `editChatSubscriptionInviteLink` | Edit subscription link |\n\n</details>\n\n<details>\n<summary><strong>Editing</strong> (9 methods)</summary>\n\n| Method | Description |\n|--------|-------------|\n| `editMessageText` | Edit text |\n| `editMessageCaption` | Edit caption |\n| `editMessageMedia` | Edit media |\n| `editMessageReplyMarkup` | Edit keyboard |\n| `editMessageLiveLocation` | Edit live location |\n| `stopMessageLiveLocation` | Stop live location |\n| `stopPoll` | Stop poll |\n| `deleteMessage` | Delete message |\n| `deleteMessages` | Delete multiple messages |\n\n</details>\n\n<details>\n<summary><strong>Settings</strong> (16 methods)</summary>\n\n| Method | Description |\n|--------|-------------|\n| `setMyCommands` | Set commands |\n| `getMyCommands` | Get commands |\n| `deleteMyCommands` | Delete commands |\n| `setMyName` | Set bot name |\n| `getMyName` | Get bot name |\n| `setMyDescription` | Set description |\n| `getMyDescription` | Get description |\n| `setMyShortDescription` | Set short description |\n| `getMyShortDescription` | Get short description |\n| `setChatMenuButton` | Set menu button |\n| `getChatMenuButton` | Get menu button |\n| `setMyDefaultAdministratorRights` | Set default admin rights |\n| `getMyDefaultAdministratorRights` | Get default admin rights |\n| `getUserProfilePhotos` | Get user photos |\n| `getFile` | Get file info |\n| `setUserEmojiStatus` | Set emoji status |\n\n</details>\n\n<details>\n<summary><strong>Business</strong> (16 methods)</summary>\n\n| Method | Description |\n|--------|-------------|\n| `getBusinessConnection` | Get connection info |\n| `readBusinessMessage` | Mark as read |\n| `deleteBusinessMessages` | Delete messages |\n| `setBusinessAccountName` | Set account name |\n| `setBusinessAccountUsername` | Set username |\n| `setBusinessAccountBio` | Set bio |\n| `setBusinessAccountProfilePhoto` | Set profile photo |\n| `removeBusinessAccountProfilePhoto` | Remove photo |\n| `setBusinessAccountGiftSettings` | Set gift settings |\n| `getBusinessAccountStarBalance` | Get star balance |\n| `transferBusinessAccountStars` | Transfer stars |\n| `postStory` | Post story |\n| `editStory` | Edit story |\n| `deleteStory` | Delete story |\n| `repostStory` | Repost story |\n| `approveSuggestedPost` | Approve post |\n| `declineSuggestedPost` | Decline post |\n\n</details>\n\n<details>\n<summary><strong>Stickers</strong> (16 methods)</summary>\n\n| Method | Description |\n|--------|-------------|\n| `getStickerSet` | Get sticker set |\n| `getCustomEmojiStickers` | Get custom emojis |\n| `uploadStickerFile` | Upload sticker |\n| `createNewStickerSet` | Create set |\n| `addStickerToSet` | Add to set |\n| `setStickerPositionInSet` | Move position |\n| `deleteStickerFromSet` | Delete from set |\n| `replaceStickerInSet` | Replace sticker |\n| `setStickerEmojiList` | Set emojis |\n| `setStickerKeywords` | Set keywords |\n| `setStickerMaskPosition` | Set mask position |\n| `setStickerSetTitle` | Set title |\n| `setStickerSetThumbnail` | Set thumbnail |\n| `setCustomEmojiStickerSetThumbnail` | Set emoji thumbnail |\n| `deleteStickerSet` | Delete set |\n\n</details>\n\n<details>\n<summary><strong>Forum Topics</strong> (13 methods)</summary>\n\n| Method | Description |\n|--------|-------------|\n| `getForumTopicIconStickers` | Get icon stickers |\n| `createForumTopic` | Create topic |\n| `editForumTopic` | Edit topic |\n| `closeForumTopic` | Close topic |\n| `reopenForumTopic` | Reopen topic |\n| `deleteForumTopic` | Delete topic |\n| `unpinAllForumTopicMessages` | Unpin all |\n| `editGeneralForumTopic` | Edit General |\n| `closeGeneralForumTopic` | Close General |\n| `reopenGeneralForumTopic` | Reopen General |\n| `hideGeneralForumTopic` | Hide General |\n| `unhideGeneralForumTopic` | Unhide General |\n| `unpinAllGeneralForumTopicMessages` | Unpin General |\n\n</details>\n\n<details>\n<summary><strong>Inline & Callbacks</strong> (6 methods)</summary>\n\n| Method | Description |\n|--------|-------------|\n| `answerInlineQuery` | Answer inline query |\n| `answerCallbackQuery` | Answer callback |\n| `answerWebAppQuery` | Answer Web App |\n| `savePreparedInlineMessage` | Save prepared message |\n| `setMessageReaction` | Set reaction |\n| `getUserChatBoosts` | Get user boosts |\n\n</details>\n\n<details>\n<summary><strong>Payments</strong> (8 methods)</summary>\n\n| Method | Description |\n|--------|-------------|\n| `sendInvoice` | Send invoice |\n| `createInvoiceLink` | Create invoice link |\n| `answerShippingQuery` | Answer shipping |\n| `answerPreCheckoutQuery` | Answer pre-checkout |\n| `getStarTransactions` | Get transactions |\n| `refundStarPayment` | Refund payment |\n| `editUserStarSubscription` | Edit subscription |\n| `getMyStarBalance` | Get balance |\n\n</details>\n\n<details>\n<summary><strong>Gifts</strong> (9 methods)</summary>\n\n| Method | Description |\n|--------|-------------|\n| `getAvailableGifts` | Get available gifts |\n| `sendGift` | Send gift |\n| `giftPremiumSubscription` | Gift Premium |\n| `getUserGifts` | Get user gifts |\n| `getChatGifts` | Get chat gifts |\n| `getBusinessAccountGifts` | Get business gifts |\n| `convertGiftToStars` | Convert to stars |\n| `upgradeGift` | Upgrade gift |\n| `transferGift` | Transfer gift |\n\n</details>\n\n<details>\n<summary><strong>Games</strong> (3 methods)</summary>\n\n| Method | Description |\n|--------|-------------|\n| `sendGame` | Send game |\n| `setGameScore` | Set score |\n| `getGameHighScores` | Get high scores |\n\n</details>\n\n<details>\n<summary><strong>Updates & Bot</strong> (7 methods)</summary>\n\n| Method | Description |\n|--------|-------------|\n| `getUpdates` | Get updates (polling) |\n| `setWebhook` | Set webhook |\n| `deleteWebhook` | Delete webhook |\n| `getWebhookInfo` | Get webhook info |\n| `getMe` | Get bot info |\n| `logOut` | Log out |\n| `close` | Close instance |\n\n</details>\n\n<details>\n<summary><strong>Verification & Passport</strong> (5 methods)</summary>\n\n| Method | Description |\n|--------|-------------|\n| `verifyUser` | Verify user |\n| `verifyChat` | Verify chat |\n| `removeUserVerification` | Remove user verification |\n| `removeChatVerification` | Remove chat verification |\n| `setPassportDataErrors` | Set Passport errors |\n\n</details>\n\n## Development\n\n```bash\nnpm test          # Run tests\nnpm run build     # Compile TypeScript\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-db4c9f8ecbfd3a27a14b152f6deacc20"}