Back to Browse
Free
Server data from the Official MCP Registry
Telegram MCP server — dual-mode Bot API + MTProto, 6 composite tools.
About
Telegram MCP server — dual-mode Bot API + MTProto, 6 composite tools.
Security Report
10.0
Low Risk10.0Low RiskValid MCP server (1 strong, 1 medium validity signals). No known CVEs in dependencies. Package registry verified. Imported from the Official MCP Registry. Trust signals: trusted author (8/8 approved).
4 files analyzed · 1 issue found
Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.
Permissions Required
This plugin requests these system permissions. Most are normal for its category.
What You'll Need
Set these up before or after installing:
Telegram bot token from @BotFather (for bot mode)Required
Environment variable: TELEGRAM_BOT_TOKEN
Telegram API ID from my.telegram.org (for user mode)
Environment variable: TELEGRAM_API_ID
Telegram API hash from my.telegram.org (for user mode)Required
Environment variable: TELEGRAM_API_HASH
How to Install
Add this to your MCP configuration file:
{
"mcpServers": {
"io-github-n24q02m-better-telegram-mcp": {
"env": {
"TELEGRAM_API_ID": "your-telegram-api-id-here",
"TELEGRAM_API_HASH": "your-telegram-api-hash-here",
"TELEGRAM_BOT_TOKEN": "your-telegram-bot-token-here"
},
"args": [
"better-telegram-mcp"
],
"command": "uvx"
}
}
}Documentation
View on GitHubFrom the project's GitHub README.
Better Telegram MCP
mcp-name: io.github.n24q02m/better-telegram-mcp
Telegram for AI agents -- messages, chats, media, and contacts across both bot and full user-account modes.
| Project | Tagline | Tag |
|---|---|---|
| better-code-review-graph | Knowledge graph for token-efficient code reviews -- semantic search and call-... | MCP |
| better-email-mcp | IMAP/SMTP email for AI agents -- read, send, organize folders, and manage att... | MCP |
| better-godot-mcp | Composite MCP server for Godot Engine -- 17 composite tools for AI-assisted g... | MCP |
| better-notion-mcp | Markdown-first Notion for AI agents -- pages, databases, blocks, and comments... | MCP |
| better-telegram-mcp | Telegram for AI agents -- messages, chats, media, and contacts across both bo... | MCP |
| claude-plugins | Claude Code plugin marketplace for the n24q02m MCP servers -- install web sea... | Marketplace |
| imagine-mcp | Image and video understanding + generation for AI agents -- across Gemini, Op... | MCP |
| jules-task-archiver | Chrome Extension for bulk operations on Jules tasks via batchexecute API -- a... | Tooling |
| mcp-core | Shared foundation for building MCP servers -- Streamable HTTP transport, OAut... | MCP |
| mnemo-mcp | Persistent AI memory with hybrid search and embedded sync. Open, free, unlimi... | MCP |
| qwen3-embed | Lightweight Qwen3 text embedding and reranking via ONNX Runtime and GGUF | Library |
| skret | Secrets without the server. | CLI |
| tacet | TACET: a self-distilling neuro-symbolic cascade that amortises LLM cost in kn... | Tooling |
| web-core | Shared web infrastructure package for search, scraping, HTTP security, and st... | Library |
| wet-mcp | Open-source MCP server for AI agents: web search, content extraction, and lib... | MCP |
Table of contents
Features
- Dual mode -- Bot API (httpx) for bots, MTProto (Telethon) for user accounts
- 7 tools with action dispatch:
message,chat,media,contact,config,help,config__open_relay - 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
Status
2026-05-02 -- Architecture stabilization update
Past months saw significant churn around credential handling and the daemon-bridge auto-spawn pattern. This caused multi-process races, browser tab spam, and inconsistent setup UX across plugins. As of v<auto>, the architecture is stable: 2 clean modes (stdio + HTTP), no daemon-bridge layer, no auto-spawn from stdio.
Apologies for the instability period. If you encountered issues with prior versions, please update to v<auto>+ and follow the current Setup docs -- most prior workarounds are no longer needed.
Related plugins from the same author:
- wet-mcp -- Web search + content extraction
- mnemo-mcp -- Persistent AI memory
- imagine-mcp -- Image/video understanding + generation
- better-notion-mcp -- Notion API
- better-email-mcp -- Email management
- better-telegram-mcp -- Telegram
- better-godot-mcp -- Godot Engine
- better-code-review-graph -- Code review knowledge graph
All plugins share the same architecture -- install once, learn pattern transfers.
Documentation
Full docs at mcp.n24q02m.com/servers/better-telegram-mcp/setup/:
- Setup -- install methods for Claude Code, Codex, Gemini CLI, Cursor, Windsurf, mcp.json
- Modes overview -- stdio / local-relay / remote-relay / remote-oauth
- Multi-user setup -- per-JWT-sub credential model
Install with AI agent -- paste this to your AI coding agent:
Install MCP server
better-telegram-mcpfollowing the steps at https://raw.githubusercontent.com/n24q02m/claude-plugins/main/plugins/better-telegram-mcp/setup-with-agent.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 |
config__open_relay | -- | Re-trigger the zero-config relay setup flow (prints a fresh relay URL for the browser form). Registered via mcp-core's register_open_relay_tool so an LLM can restart setup without a manual restart |
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 |
Comparison
How better-telegram-mcp stacks up against direct competitors in each pillar:
| Capability | better-telegram-mcp | chigwell/telegram-mcp | sparfenyuk/mcp-telegram | guangxiangdebizi/telegram-mcp |
|---|---|---|---|---|
| Bot API mode (bot token) | Yes (httpx) | No | No | Yes |
| MTProto user-account mode | Yes (Telethon) | Yes | Yes | No |
| Send / edit / delete messages | Yes | Yes | No (read-only, draft only) | Yes (send only) |
| Media download from messages | Yes | Yes | Yes | No (send only) |
| Contact management (add / block) | Yes (user mode) | Yes | Partial (list only) | No |
| Web-based / browser OTP auth | Yes (relay form, headless) | No (CLI session string) | No (CLI sign-in) | No (pre-set bot token) |
| Multi-user remote, per-user isolation | Yes (per-JWT-sub backends) | No | No | No |
| SSRF protection | Yes (URL validation + DNS-rebinding) | ? | ? | No |
| Path-traversal prevention | Yes | Yes (real-path allowed-root) | ? | No |
| Self-hostable | Yes | Yes | Yes | Yes |
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
Trust Model
This plugin implements TC-NearZK (in-memory, ephemeral). See mcp-core trust model for full classification.
| Mode | Storage | Encryption | Who can read your data? |
|---|---|---|---|
| HTTP n24q02m-hosted (default) | In-memory dict[sub] = MTProtoSession | In-process only | Server process (cleared on restart) |
| HTTP self-host | Same as hosted | Same | Only you (admin = user) |
| stdio | ~/.config/mcp/config.enc (credentials) + ~/.better-telegram-mcp/<name>.session (Telethon session) | AES-GCM, machine-bound key | Only your OS user (file perm 0600) |
License
MIT -- See LICENSE.
Reviews
No reviews yet
Be the first to review this server!
More Communication MCP Servers
Toleno
Freeby Toleno · Developer Tools
Toleno Network MCP Server — Manage your Toleno mining account with Claude AI using natural language.
137
Stars
517
Installs
8.0
Security
4.8
Local
mcp-creator-python
Freeby mcp-marketplace · Developer Tools
Create, build, and publish Python MCP servers to PyPI — conversationally.
-
Stars
72
Installs
10.0
Security
4.6
Local
MarkItDown
Freeby Microsoft · Content & Media
Convert files (PDF, Word, Excel, images, audio) to Markdown for LLM consumption
156.1K
Stars
33
Installs
6.0
Security
5.0
Local