leshchenko1979/fast-mcp-telegram
If you are the rightful owner of fast-mcp-telegram and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
MCP Telegram Server is a robust implementation using FastMCP, offering Telegram functionalities through a streamlined API, including search and messaging capabilities.
Fast MCP Telegram Server - Production-ready Telegram integration for AI assistants with comprehensive search, messaging, and direct API access capabilities.
๐ Demo
- Open https://tg-mcp.redevest.ru/setup to begin the authentication flow.
- After finishing, you'll receive a ready-to-use
mcp.jsonwith your Bearer token. - Use the config with your MCP client to check out this MCP server capabilities.
- Or try the HTTPโMTProto Bridge right away with curl (replace TOKEN):
curl -X POST "https://tg-mcp.redevest.ru/mtproto-api/messages.SendMessage" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"params": {"peer": "me", "message": "Hello from Demo!"}}'
๐ Table of Contents
- โจ Features
- ๐ Quick Start
- ๐๏ธ Server Modes
- ๐ HTTP-MTProto Bridge
- ๐ Documentation
- ๐ Security
- ๐ค Contributing
- ๐ License
โจ Features
| Feature | Description |
|---|---|
| ๐ Multi-User Authentication | Production-ready Bearer token auth with session isolation and LRU cache management |
| ๐ HTTP-MTProto Bridge | Direct curl access to any Telegram API method with entity resolution and safety guardrails |
| ๐ Intelligent Search | Global & per-chat message search with multi-query support and intelligent deduplication |
| ๐๏ธ Dual Transport | Seamless development (stdio) and production (HTTP) deployment support |
| ๐ Secure File Handling | Rich media sharing with SSRF protection, size limits, and album support |
| ๐ฌ Advanced Messaging | Send, edit, reply with formatting, file attachments, and phone number messaging |
| ๐ Enterprise Session Management | Zero-downtime deployments with automatic backup/restore and health monitoring |
| ๐ฅ Smart Contact Discovery | Search users, groups, channels with uniform entity schemas and profile enrichment |
| โก High Performance | Async operations, parallel queries, connection pooling, and memory optimization |
| ๐ก๏ธ Production Reliability | Auto-reconnect, structured logging, comprehensive error handling |
| ๐ฏ AI-Optimized | Literal parameter constraints and LLM-friendly API design |
| ๐ Web Setup Interface | Browser-based authentication flow with immediate config generation |
๐ Quick Start
1. Install from PyPI
pip install fast-mcp-telegram
2. Authenticate with Telegram
fast-mcp-telegram-setup --api-id="your_api_id" --api-hash="your_api_hash" --phone-number="+123456789"
๐ Prefer a browser? Run the server and open /setup to authenticate and download a readyโtoโuse mcp.json.
3. Configure Your MCP Client
STDIO Mode (Development with Cursor IDE):
{
"mcpServers": {
"telegram": {
"command": "fast-mcp-telegram",
"env": {
"API_ID": "your_api_id",
"API_HASH": "your_api_hash",
"PHONE_NUMBER": "+123456789"
}
}
}
}
HTTP_AUTH Mode (Production with Bearer Token):
{
"mcpServers": {
"telegram": {
"url": "https://your-server.com",
"headers": {
"Authorization": "Bearer AbCdEfGh123456789KLmnOpQr..."
}
}
}
}
4. Start Using!
{"tool": "search_messages_globally", "params": {"query": "hello", "limit": 5}}
{"tool": "send_message", "params": {"chat_id": "me", "message": "Hello from AI!"}}
๐ For detailed installation instructions, see
๐๏ธ Server Modes
| Mode | Transport | Authentication | Use Case |
|---|---|---|---|
| STDIO | stdio | Disabled | Development with Cursor IDE |
| HTTP_NO_AUTH | HTTP | Disabled | Development HTTP server |
| HTTP_AUTH | HTTP | Required (Bearer token) | Production deployment |
๐ HTTP-MTProto Bridge
Direct curl access to any Telegram API method - Execute any Telegram MTProto method via HTTP requests with automatic entity resolution and safety guardrails.
Quick Examples
# Send message with automatic entity resolution
curl -X POST "https://your-domain.com/mtproto-api/messages.SendMessage" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"params": {"peer": "@username", "message": "Hello from curl!"},
"resolve": true
}'
# Send message using params_json (works with n8n and other tools)
curl -X POST "https://your-domain.com/mtproto-api/messages.SendMessage" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"params_json": "{\"peer\": \"@username\", \"message\": \"Hello from curl!\"}",
"resolve": true
}'
# Get message history with peer resolution
curl -X POST "https://your-domain.com/mtproto-api/messages.getHistory" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"params": {"peer": "me", "limit": 10},
"resolve": true
}'
๐ For complete MTProto Bridge documentation, see
๐ Documentation
- - Detailed installation and configuration
- - Docker deployment and production setup
- - Complete tools documentation with examples
- - Search best practices and limitations
- - Health monitoring and troubleshooting
- - Code organization and architecture
- - Development setup and contribution guidelines
๐ Security
Key Security Features:
- Bearer token authentication with session isolation
- SSRF protection for file downloads
- Dangerous method blocking with opt-in override
- Session file security and automatic cleanup
๐ For complete security information, see
๐ค Contributing
We welcome contributions! Please see our for:
- Development setup instructions
- Testing guidelines
- Code quality standards
- Pull request process
Quick Start for Contributors:
- Fork the repository
- Read the
- Create a feature branch
- Make your changes and add tests
- Submit a pull request
๐ License
This project is licensed under the MIT License - see the file for details.
๐ Acknowledgments
- FastMCP - MCP server framework
- Telethon - Telegram API library
- Model Context Protocol - Protocol specification
Made with โค๏ธ for the AI automation community
mcp-name: io.github.leshchenko1979/fast-mcp-telegram
