Telegram MCP Server
Production-ready MCP server for the complete Telegram Bot API. 162 methods with token-optimized meta mode (~157 tokens vs ~55,000).
Highlights
- Complete API coverage: All 162 Telegram Bot API methods
- Token efficient: Meta mode reduces context by 99.7%
- Production hardened: Circuit breaker, rate limiting, retries with backoff
- Observable: Prometheus metrics, structured logging, health checks
- Type safe: Full TypeScript with Zod validation
Installation
npm install @tonresistor/telegram-mcp
Or clone and build from source:
git clone https://github.com/TONresistor/telegram-mcp.git
cd telegram-mcp && npm install && npm run build
Quick Start
Get your bot token from @BotFather, then add to your MCP config:
{
"mcpServers": {
"telegram": {
"command": "node",
"args": ["/path/to/build/index-meta.js"],
"env": {
"TELEGRAM_BOT_TOKEN": "your_token_here"
}
}
}
}
Usage Modes
Meta mode exposes just 2 tools:
telegram_find: Search methods by name or categorytelegram_call: Execute any Telegram API method
Configuration
Features
Resilience
- Circuit breaker: Opens after 5 failures, auto-recovers after 30s
- Rate limiting: Global + per-chat (respects Telegram limits)
- Retries: Exponential backoff with jitter
Observability
- Prometheus metrics: Request counts, latencies, error rates
- Health checks: Kubernetes-ready readiness/liveness probes
- Structured logging: JSON format with automatic secret redaction
API Reference
All 161 Telegram Bot API methods organized by category.
Development
npm test # Run tests
npm run build # Compile TypeScript
License
MIT
