Telegram API MCP
telegram-api-mcp
MCP server for the Telegram Bot API: messages, channels, forums, payments and long posts from a bot, with Telegram rate limits built in
Install
claude mcp add telegram -- npx telegram-api-mcp -e TELEGRAM_BOT_TOKEN=your_tokenAdd -e TELEGRAM_META_MODE=true to save context.
This is third-party code. Review the repository files before installing.
What it does
The server exposes every Telegram Bot API method to the agent: sending and editing messages, media, polls, chat and member management, forums, stickers, payments, stories and gifts. Long posts with headings, tables and media go out as rich messages, and the telegram_format tool tells the agent the exact shape of complex parameters before it sends anything. Meta-mode replaces the full tool list with two tools, method search and method call, to save context. It ships rate limiting, retries on 429 and 5xx, a circuit breaker and Zod parameter validation.
Who it is for. For people who run Telegram channels and groups or build bots and want to drive them through an agent.
Good fit when
- You want to publish channel posts from a bot straight from the agent
- You need to moderate a group: pin, delete, restrict members
- You are debugging a bot and want to try Bot API methods without writing code
Not a fit when
- You need a personal Telegram account rather than a bot
- The agent must not be able to post or delete messages in live chats
Example request
Post to @mychannel a message with a heading, a price table and an imageLimitations
It acts only as a bot: you need a BotFather token, and the bot must be added to target chats with admin rights. Media captions still follow Telegram's limit, long texts need send_rich_message. The server talks only to api.telegram.org, and whether that host is reachable from Russia without a VPN depends on the ISP.
How to disable. Run claude mcp remove telegram or delete the telegram block from the MCP client config. The bot token can be revoked in BotFather.
MCP
- Transport
- stdio
- Authentication
- API key
| Environment variables | |
|---|---|
| TELEGRAM_BOT_TOKEN required, secret | Bot token from BotFather |
| TELEGRAM_DEFAULT_CHAT_ID | Default chat for all tools |
| TELEGRAM_META_MODE | true enables the two-tool mode |
| TELEGRAM_ALLOWED_UPLOAD_DIRS | Comma-separated directories allowed for file uploads |
Security check
- The agent can post and delete messages and ban members as the bot
- Includes payment and gift methods paid in Telegram Stars
- Requires a secret bot token
README in short
The README lists Bot API coverage by category, from messages and chats to business accounts and managed bots. It gives setup commands for Claude Code and Claude Desktop, a default-chat variant and a build from source. It separately covers rich messages with their limits, meta-mode, the declarative method registry and a script that diffs the registry against official docs. The security section mentions token masking, upload path checks and no telemetry. MIT license.
FAQ
Why meta-mode?
Instead of the full tool set the agent sees two tools, telegram_find and telegram_call. Context use drops sharply while the whole API stays reachable.
Can the token leak into agent output?
No, according to the README the token is masked in responses, logs and error messages.
Related
Marketing Skills for AI agents
Marketing Skills for AI Agents
About fifty skills for CRO, copywriting, SEO, analytics, ads and launches, built for coding agents
A skill that strips AI writing tells from text using Wikipedia's list, without adding invented facts
Content skills: article illustrations, covers, infographics, comics, translation, URL to Markdown and social posting
The Chinese version of Humanizer: finds and removes signs of AI writing in Chinese text