io.github.n24q02m/better-telegram-mcp icon

better-telegram-mcp

by N24q02m

io.github.n24q02m/better-telegram-mcp

Telegram MCP server — dual-mode Bot API + MTProto, 6 composite tools.

Version 4.10.0
Messaging
Local
View source

better-telegram-mcp · v4.10.0

by N24q02m

98

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.

CI
codecov

Sister projects from n24q02m (click to expand)
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:

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-mcp following 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.