Production-grade MCP server for Telegram — dual-mode Bot API + MTProto, domain-separated tools
Verified details
These details have been verified by PyPIProject links
GitHub Statistics
Maintainers
Project description
Better Telegram MCP
mcp-name: io.github.n24q02m/better-telegram-mcp
MCP server for Telegram with dual-mode support: Bot API (httpx) for quick bot integrations and MTProto (Telethon) for full user-account access.
Features
- Dual mode -- Bot API (httpx) for bots, MTProto (Telethon) for user accounts
- 6 tools with action dispatch:
message,chat,media,contact,config,help - Auto-detect mode -- Set bot token for bot mode, or API credentials for user mode
- Web-based OTP auth -- Browser-based authentication with remote relay support for headless environments
- Tool annotations -- Each tool declares
readOnlyHint,destructiveHint,idempotentHint,openWorldHint - MCP Resources -- Documentation available as
telegram://docs/*resources - Security hardened -- SSRF protection, path traversal prevention, error sanitization
Setup
With AI Agent -- copy and send this to your AI agent:
Please set up better-telegram-mcp for me. Follow this guide: https://raw.githubusercontent.com/n24q02m/better-telegram-mcp/main/docs/setup-with-agent.md
Manual Setup -- follow docs/setup-manual.md
Tools
| Tool | Actions | Description |
|---|---|---|
message |
send, edit, delete, forward, pin, react, search, history |
Send, edit, delete, forward messages. Pin, react, search, browse history |
chat |
list, info, create, join, leave, members, admin, settings, topics |
List and manage chats, groups, channels. Members, admin, forum topics |
media |
send_photo, send_file, send_voice, send_video, download |
Send photos, files, voice notes, videos. Download media from messages |
contact |
list, search, add, block |
List, search, add contacts. Block/unblock users (user mode only) |
config |
status, set, cache_clear, setup_status, setup_start, setup_reset, setup_complete |
Server status, runtime settings, cache, credential setup (relay, status, reset, complete) |
help |
-- | Full documentation for any topic |
MCP Resources
| URI | Content |
|---|---|
telegram://docs/messages |
Message operations reference |
telegram://docs/chats |
Chat management reference |
telegram://docs/media |
Media send/download reference |
telegram://docs/contacts |
Contact management reference |
telegram://stats |
All documentation combined |
Security
- SSRF Protection -- All URLs validated against internal/private IP ranges, DNS rebinding blocked
- Path Traversal Prevention -- File paths validated, sensitive directories blocked
- Session File Security -- 600 permissions, 2FA via web UI only (never stored in env vars)
- Error Sanitization -- Credentials never leaked in error messages
Build from Source
git clone https://github.com/n24q02m/better-telegram-mcp.git
cd better-telegram-mcp
uv sync
uv run better-telegram-mcp
License
MIT -- See LICENSE.
Project details
Verified details
These details have been verified by PyPIProject links
GitHub Statistics
Maintainers
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file better_telegram_mcp-4.4.0.tar.gz.
File metadata
- Download URL: better_telegram_mcp-4.4.0.tar.gz
- Upload date:
- Size: 186.3 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via: uv/0.11.6 {"installer":{"name":"uv","version":"0.11.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
151592b8cb5015d7239a747ae16876ffcdba8f327f4df71ad0e2dddbdc996b1d
|
|
| MD5 |
121d6929dfcb9a4725455ec2b81a9fb9
|
|
| BLAKE2b-256 |
bb58a285fe0bcaa7bf2e282e36ca87adc78f171aff10704e5018beab40dc0633
|
File details
Details for the file better_telegram_mcp-4.4.0-py3-none-any.whl.
File metadata
- Download URL: better_telegram_mcp-4.4.0-py3-none-any.whl
- Upload date:
- Size: 69.9 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via: uv/0.11.6 {"installer":{"name":"uv","version":"0.11.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
3fd2fbad35aa237ad5d31e655311c18f5b5fe101b874977166ce2877b06371cb
|
|
| MD5 |
06eb21abcf1300c4626ed24402745ee8
|
|
| BLAKE2b-256 |
9cf8babb5bd291a593b1c1ae7a3c8aed3a8f603903cf19e8e8cbdf3176fa0ccb
|
