{"_id":"@mseep/telegram-api-mcp","name":"@mseep/telegram-api-mcp","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@mseep/telegram-api-mcp","version":"0.1.0","description":"Ultimate Telegram Bot API v9.6 MCP Server — 169 methods, meta-mode, rate limiting, circuit breaker","type":"module","main":"dist/index.js","bin":{"telegram-api-mcp":"dist/index.js"},"scripts":{"build":"tsc","dev":"tsx src/index.ts","start":"node dist/index.js","test":"vitest run","test:watch":"vitest","test:coverage":"vitest run --coverage","typecheck":"tsc --noEmit","lint":"eslint src/","prepublishOnly":"npm run build"},"keywords":["telegram","bot-api","mcp","mcp-server","model-context-protocol","claude","ai-agent","mseep"],"author":{"name":"timoncool"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/timoncool/telegram-api-mcp.git"},"engines":{"node":">=18.0.0"},"dependencies":{"@modelcontextprotocol/sdk":"^1.12.0","zod":"^3.24.0"},"devDependencies":{"@types/node":"^22.0.0","@typescript-eslint/eslint-plugin":"^8.58.0","@typescript-eslint/parser":"^8.58.0","eslint":"^10.2.0","tsx":"^4.19.0","typescript":"^5.7.0","vitest":"^3.0.0"},"publisher":"mseep","_id":"@mseep/telegram-api-mcp@0.1.0","gitHead":"c9c65ec4ebc473777eb56f0f9053e1bec5a245d5","types":"./dist/index.d.ts","bugs":{"url":"https://github.com/timoncool/telegram-api-mcp/issues"},"homepage":"https://github.com/timoncool/telegram-api-mcp#readme","_nodeVersion":"18.20.8","_npmVersion":"10.8.2","dist":{"integrity":"sha512-EKuQ0WBsvxhRkWPtStEJTW+yMRyzhQ7hQ1YEwjfCdnhY3A9yi+epiXaqPz5IUOnHY3RPwnAIiM24bwzdwEM/sA==","shasum":"ec75d0f0852c979cc775f873839d162fecb9878d","tarball":"https://registry.npmjs.org/@mseep/telegram-api-mcp/-/telegram-api-mcp-0.1.0.tgz","fileCount":113,"unpackedSize":357163,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIBx+jRpXuPbb20qy2plm2jxdzmbh6kJXlLuyophvKkmmAiEA/CXgaiFY3JZIb1UnqASE3uL35Va+7FF050/NKZIOKyw="}]},"_npmUser":{"name":"skydeckai","email":"support@skydeck.ai"},"directories":{},"maintainers":[{"name":"skydeckai","email":"support@skydeck.ai"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/telegram-api-mcp_0.1.0_1782108216421_0.6955017134314319"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-22T06:03:36.286Z","0.1.0":"2026-06-22T06:03:36.554Z","modified":"2026-06-22T06:03:36.770Z"},"maintainers":[{"name":"skydeckai","email":"support@skydeck.ai"}],"description":"Ultimate Telegram Bot API v9.6 MCP Server — 169 methods, meta-mode, rate limiting, circuit breaker","homepage":"https://github.com/timoncool/telegram-api-mcp#readme","keywords":["telegram","bot-api","mcp","mcp-server","model-context-protocol","claude","ai-agent","mseep"],"repository":{"type":"git","url":"git+https://github.com/timoncool/telegram-api-mcp.git"},"author":{"name":"timoncool"},"bugs":{"url":"https://github.com/timoncool/telegram-api-mcp/issues"},"license":"MIT","readme":"
\n\n# telegram-api-mcp\n\n**Ultimate MCP server for Telegram Bot API — 169 methods, full v9.6 coverage, meta-mode, rate limiting, circuit breaker.**\n\n[](https://github.com/timoncool/telegram-api-mcp/stargazers)\n[](https://www.npmjs.com/package/telegram-api-mcp)\n[](LICENSE)\n[](https://core.telegram.org/bots/api)\n[](https://github.com/timoncool/trail-spec)\n\n
\n\n169/169 Bot API methods with Zod validation, token masking, tool annotations, and zero bloat (2 dependencies).\n\n## Features\n\n- **169/169 Bot API methods** — messages, media, polls, chats, forums, stickers, payments, business, stories, gifts, games, inline, managed bots\n- **Bot API 9.6** (April 2026) — managed bots, revoting polls, shuffle options, poll descriptions\n- **Meta-mode** — 2 tools instead of 169, saves ~99% context tokens\n- **Rate limiting** — global (30 req/sec) + per-chat (20 msg/min), token bucket with async mutex\n- **Circuit breaker** — 3-state (closed/open/half-open), auto-recovery\n- **Retry with backoff** — respects Telegram 429 `retry_after`, exponential backoff on 5xx\n- **Zod validation** — every parameter validated before hitting Telegram API\n- **Token masking** — bot token never appears in responses, logs, or error messages\n- **File upload security** — path traversal protection, configurable allowed directories\n- **Tool annotations** — all 169 methods annotated (readOnly, destructive, idempotent, openWorld)\n- **Response truncation** — 100K char limit to prevent context overflow\n- **Zero bloat** — only 2 dependencies: `@modelcontextprotocol/sdk` + `zod`\n\n## Quick Start\n\n### Claude Code\n\n```bash\nclaude mcp add telegram -- npx telegram-api-mcp -e TELEGRAM_BOT_TOKEN=your_token\n```\n\nWith meta-mode (recommended for large conversations):\n\n```bash\nclaude mcp add telegram -- npx telegram-api-mcp \\\n -e TELEGRAM_BOT_TOKEN=your_token \\\n -e TELEGRAM_META_MODE=true\n```\n\n### Claude Desktop\n\nAdd to `claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"telegram\": {\n \"command\": \"npx\",\n \"args\": [\"telegram-api-mcp\"],\n \"env\": {\n \"TELEGRAM_BOT_TOKEN\": \"your_token_from_botfather\"\n }\n }\n }\n}\n```\n\n### With default chat (skip chat_id in every call)\n\n```json\n{\n \"mcpServers\": {\n \"telegram\": {\n \"command\": \"npx\",\n \"args\": [\"telegram-api-mcp\"],\n \"env\": {\n \"TELEGRAM_BOT_TOKEN\": \"your_token\",\n \"TELEGRAM_DEFAULT_CHAT_ID\": \"-1001234567890\"\n }\n }\n }\n}\n```\n\n### From source\n\n```bash\ngit clone https://github.com/timoncool/telegram-api-mcp.git\ncd telegram-api-mcp\nnpm install && npm run build\nTELEGRAM_BOT_TOKEN=your_token node dist/index.js\n```\n\n## Environment Variables\n\n| Variable | Required | Default | Description |\n|----------|:---:|:---:|-------------|\n| `TELEGRAM_BOT_TOKEN` | **Yes** | — | Bot token from [@BotFather](https://t.me/BotFather) |\n| `TELEGRAM_DEFAULT_CHAT_ID` | No | — | Default chat ID for all tools |\n| `TELEGRAM_DEFAULT_THREAD_ID` | No | — | Default forum topic thread ID |\n| `TELEGRAM_META_MODE` | No | `false` | Use 2 meta-tools instead of 169 |\n| `TELEGRAM_GLOBAL_RATE_LIMIT` | No | `30` | Max requests/sec ([Telegram limit](https://core.telegram.org/bots/faq#my-bot-is-hitting-limits)) |\n| `TELEGRAM_PER_CHAT_RATE_LIMIT` | No | `20` | Max messages/min per group ([Telegram limit](https://core.telegram.org/bots/faq#my-bot-is-hitting-limits)) |\n| `TELEGRAM_MAX_RETRIES` | No | `3` | Retry attempts on transient errors |\n| `TELEGRAM_CB_THRESHOLD` | No | `5` | Failures before circuit opens |\n| `TELEGRAM_CB_COOLDOWN` | No | `30000` | Circuit breaker cooldown (ms) |\n| `TELEGRAM_ALLOWED_UPLOAD_DIRS` | No | — | Comma-separated allowed upload paths |\n| `TELEGRAM_MAX_FILE_SIZE` | No | `52428800` | Max upload file size (50MB) |\n\n## Meta Mode\n\nWhen `TELEGRAM_META_MODE=true`, the server exposes only 2 tools instead of 169:\n\n- **`telegram_find`** — search methods by keyword or category\n- **`telegram_call`** — call any method by name with JSON params\n\nThis saves ~99% of context tokens while keeping full API access:\n\n```\nUser: \"Post a poll in my channel\"\nAI: → telegram_find(query: \"poll\")\nAI: → telegram_call(method: \"sendPoll\", params: { chat_id: ..., question: \"...\", options: [...] })\n```\n\n## API Coverage\n\n169/169 methods — **100% Bot API 9.6** (April 2026)\n\n| Category | Count | Key methods |\n|----------|:---:|-------------|\n| Bot | 21 | getMe, setMyCommands, setMyProfilePhoto, getFile, getUserProfilePhotos |\n| Stickers | 16 | sendSticker, createNewStickerSet, uploadStickerFile, setStickerKeywords |\n| Chat | 15 | getChat, setChatTitle, setChatPermissions, pinChatMessage, leaveChat |\n| Business | 14 | readBusinessMessage, setBusinessAccountName, getBusinessConnection |\n| Forum | 13 | createForumTopic, editForumTopic, closeForumTopic, deleteForumTopic |\n| Editing | 10 | editMessageText, editMessageMedia, deleteMessage, deleteMessages, stopPoll |\n| Messages | 9 | sendMessage, sendMessageDraft, sendLocation, sendContact, sendChecklist |\n| Media | 9 | sendPhoto, sendVideo, sendAudio, sendDocument, sendMediaGroup, sendPaidMedia |\n| Members | 9 | banChatMember, promoteChatMember, setChatMemberTag, restrictChatMember |\n| Invite | 8 | createChatInviteLink, createChatSubscriptionInviteLink, approveChatJoinRequest |\n| Payments | 8 | sendInvoice, createInvoiceLink, getStarTransactions, getMyStarBalance |\n| Gifts | 8 | sendGift, getUserGifts, getChatGifts, giftPremiumSubscription, upgradeGift |\n| Other | 5 | verifyUser, verifyChat, setUserEmojiStatus, savePreparedInlineMessage |\n| Forwarding | 4 | forwardMessage, forwardMessages, copyMessage, copyMessages |\n| Stories | 4 | postStory, editStory, deleteStory, repostStory |\n| Inline | 4 | answerInlineQuery, answerCallbackQuery, answerWebAppQuery, savePreparedInlineMessage |\n| Updates | 4 | getUpdates, setWebhook, deleteWebhook, getWebhookInfo |\n| Games | 3 | sendGame, setGameScore, getGameHighScores |\n| Managed Bots | 3 | getManagedBotToken, replaceManagedBotToken, savePreparedKeyboardButton |\n| Polls | 1 | sendPoll (v9.6: revoting, shuffle, multiple correct, descriptions) |\n| Passport | 1 | setPassportDataErrors |\n\n## Architecture\n\n```\nsrc/\n├── index.ts # Entry point\n├── config.ts # Environment config with validation\n├── server.ts # MCP server (standard + meta mode)\n├── telegram-client.ts # HTTP client with retry, rate limit, circuit breaker\n├── rate-limiter.ts # Token bucket: global + per-chat\n├── circuit-breaker.ts # 3-state circuit breaker (closed/open/half-open)\n├── method-registry.ts # Declarative method definitions + Zod schema builder\n└── methods/\n ├── index.ts # Aggregator + search\n ├── messages.ts # sendMessage, sendDice, sendChecklist, ...\n ├── forwarding.ts # forwardMessage, copyMessage, ...\n ├── editing.ts # editMessageText, deleteMessage, ...\n ├── chat.ts # getChat, setChatTitle, banChatMember, ...\n ├── bot.ts # getMe, setMyCommands, getFile, ...\n ├── forum.ts # createForumTopic, editForumTopic, ...\n ├── stickers.ts # sendSticker, createNewStickerSet, ...\n ├── payments.ts # sendInvoice, getStarTransactions, ...\n ├── business.ts # readBusinessMessage, setBusinessAccount*, ...\n ├── stories.ts # postStory, editStory, deleteStory, ...\n ├── gifts.ts # sendGift, getUserGifts, convertGiftToStars, ...\n ├── games.ts # sendGame, setGameScore, ...\n ├── inline.ts # answerInlineQuery, answerCallbackQuery\n ├── managed-bots.ts # getManagedBotToken, replaceManagedBotToken\n ├── updates.ts # getUpdates, setWebhook, ...\n ├── passport.ts # setPassportDataErrors\n └── other.ts # verifyUser, setChatMenuButton, ...\n```\n\n### Design principles\n\n- **Declarative registry** — each method is pure data (name, params, types, annotations). One generic handler serves all 169 methods. Adding a new method = one array entry.\n- **Zod validation** — every parameter validated before reaching Telegram. Clear error messages with hints instead of opaque API 400s.\n- **Token bucket rate limiting** — no race conditions (async mutex). Defaults match [Telegram's official limits](https://core.telegram.org/bots/faq#my-bot-is-hitting-limits): 30 req/sec global, 20 msg/min per group.\n- **Circuit breaker** — 429 (rate limit) is NOT counted as failure. Only real errors (5xx, network) trip the breaker. Half-open probe recovers automatically.\n- **Tool annotations** — every method has MCP annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) so AI clients know which tools are safe to auto-approve.\n- **Response truncation** — responses capped at 100K chars to prevent context window overflow.\n\n## Security\n\n- Bot token never appears in MCP tool responses or error messages (masked as `***`)\n- File upload paths validated against allowed directories (`TELEGRAM_ALLOWED_UPLOAD_DIRS`)\n- Path traversal attacks blocked (resolve + normalize + separator check)\n- No `eval()`, no `Function()`, no dynamic imports\n- No external requests except `api.telegram.org`\n- No telemetry, no analytics, no phone-home\n- Zero bloat: only 2 runtime dependencies (`@modelcontextprotocol/sdk` + `zod`)\n\n## Development\n\n```bash\nnpm install\nnpm run build # TypeScript compilation\nnpm run typecheck # Type checking without emit\nnpm test # Run all tests (vitest)\nnpm run test:watch # Watch mode\nnpm run lint # ESLint\n```\n\n## Other Projects by [@timoncool](https://github.com/timoncool)\n\n| Project | Description |\n|---------|-------------|\n| [civitai-mcp-ultimate](https://github.com/timoncool/civitai-mcp-ultimate) | Civitai API as MCP server |\n| [trail-spec](https://github.com/timoncool/trail-spec) | TRAIL — cross-MCP content tracking protocol |\n| [ACE-Step Studio](https://github.com/timoncool/ACE-Step-Studio) | AI music studio — songs, vocals, covers, videos |\n| [VideoSOS](https://github.com/timoncool/videosos) | AI video production in the browser |\n| [tg-challenge-bot](https://github.com/timoncool/tg-challenge-bot) | AI anti-spam bot for Telegram |\n| [Bulka](https://github.com/timoncool/Bulka) | Live-coding music platform |\n\n## Support the Author\n\nI build open-source software and do AI research. Most of what I create is free and available to everyone. Your donations help me keep creating without worrying about where the next meal comes from =)\n\n**[All donation methods](https://github.com/timoncool/ACE-Step-Studio/blob/master/DONATE.md)** | **[dalink.to/nerual_dreming](https://dalink.to/nerual_dreming)** | **[boosty.to/neuro_art](https://boosty.to/neuro_art)**\n\n- **BTC:** `1E7dHL22RpyhJGVpcvKdbyZgksSYkYeEBC`\n- **ETH (ERC20):** `0xb5db65adf478983186d4897ba92fe2c25c594a0c`\n- **USDT (TRC20):** `TQST9Lp2TjK6FiVkn4fwfGUee7NmkxEE7C`\n\n\n## Star History\n\n\n \n \n \n \n \n\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-51f274ec16cd34b763f2ce9961ffe10e"}