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 |
| 🎤 Voice Transcription | Automatic speech-to-text for Premium accounts with parallel processing and polling |
| 📊 Unified Session Management | Single configuration system for setup and server, with multi-account support |
| 👥 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 with clear actionable messages |
| 🎯 AI-Optimized | Literal parameter constraints, LLM-friendly API design, and MCP ToolAnnotations |
| 🌍 Web Setup Interface | Browser-based authentication flow with immediate config generation |
🛠️ Available Tools
| Tool | Purpose | Key Features |
|---|---|---|
search_messages_globally |
Search across all chats | Multi-term queries, date filtering, chat type filtering |
search_messages_in_chat |
Search within specific chat | Supports "me" for Saved Messages, optional query for latest messages |
send_message |
Send new message | File attachments (URLs/local), formatting (markdown/html), replies |
edit_message |
Edit existing message | Text formatting, preserves message structure |
read_messages |
Read specific messages by ID | Batch reading, full message content, voice transcription for Premium accounts |
find_chats |
Find users/groups/channels | Multi-term search, contact discovery, username/phone lookup |
get_chat_info |
Get detailed profile info | Member counts, bio/about, online status, enriched data |
send_message_to_phone |
Message phone numbers | Auto-contact management, optional cleanup, file support |
invoke_mtproto |
Direct Telegram API access | Raw MTProto methods, entity resolution, safety guardrails |
📖 For detailed tool documentation with examples, see Tools Reference
🚀 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. You can also reauthorize existing sessions through the same interface.
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 Installation Guide
🏗️ 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 MTProto Bridge Guide
📚 Documentation
- Installation Guide - Detailed installation and configuration
- Deployment Guide - Docker deployment and production setup
- Tools Reference - Complete tools documentation with examples
- Search Guidelines - Search best practices and limitations
- Operations Guide - Health monitoring and troubleshooting
- Project Structure - Code organization and architecture
- Contributing Guide - 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 SECURITY.md
🤝 Contributing
We welcome contributions! Please see our Contributing Guide for:
- Development setup instructions
- Testing guidelines
- Code quality standards
- Pull request process
Quick Start for Contributors:
- Fork the repository
- Read the Contributing Guide
- 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 LICENSE 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
Metadata
Release files for iflow-mcp_leshchenko1979_fast-mcp-telegram 0.11.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| iflow_mcp_leshchenko1979_fast_mcp_telegram-0.11.0.tar.gz | 83.3 kB | Without provenance | Details for iflow_mcp_leshchenko1979_fast_mcp_telegram-0.11.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| iflow_mcp_leshchenko1979_fast_mcp_telegram-0.11.0-py3-none-any.whl | Python 3 | none | any | Details for iflow_mcp_leshchenko1979_fast_mcp_telegram-0.11.0-py3-none-any.whl |
Total release size: 159.4 kB
Release files / iflow_mcp_leshchenko1979_fast_mcp_telegram-0.11.0.tar.gz
| Download URL | iflow_mcp_leshchenko1979_fast_mcp_telegram-0.11.0.tar.gz |
|---|---|
| Size | 83.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
56f69e8f2bdd3c56fd5dd6ddbcf42e22eed6cba1cfb0db8a35ba147fc025094f
|
|
BLAKE2b-256 checksum How to use checksums |
2df517551f22527000a6c8c166ff131b577d3362e732467943aa731844f05f60
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.28 {"installer":{"name":"uv","version":"0.9.28","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / iflow_mcp_leshchenko1979_fast_mcp_telegram-0.11.0-py3-none-any.whl
| Download URL | iflow_mcp_leshchenko1979_fast_mcp_telegram-0.11.0-py3-none-any.whl |
|---|---|
| Size | 76.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
caa6df5bef36dbe57ac80ada2ff85946bca5a0a9566dbeafd6154dedf420f04d
|
|
BLAKE2b-256 checksum How to use checksums |
6ab228de59f53c9c9da9b9fe9292e2659a47843c4110561bbe57c0b5ba93ff1a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.28 {"installer":{"name":"uv","version":"0.9.28","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for iflow-mcp_leshchenko1979_fast-mcp-telegram 0.11.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.