About io.github.n24q02m/better-telegram-mcp
io.github.n24q02m/better-telegram-mcp is an MCP server in the Commerce category: telegram MCP server — dual-mode Bot API + MTProto, 6 composite tools.
Install
uvx better-telegram-mcppip install better-telegram-mcpThis server has no ConduID identity, so agent calls to it are not receipted. Pin the version you install and review the source before granting it credentials.
Tools (7)
chat`list`, `info`, `create`, `join`, `leave`, `members`, `admin`, `settings`, `topics`
Parameters not published.
config`status`, `set`, `cache_clear`, `setup_status`, `setup_start`, `setup_reset`, `setup_complete`
Parameters not published.
config__open_relay--
Parameters not published.
contact`list`, `search`, `add`, `block`
Parameters not published.
help--
Parameters not published.
media`send_photo`, `send_file`, `send_voice`, `send_video`, `download`
Parameters not published.
message`send`, `edit`, `delete`, `forward`, `pin`, `react`, `search`, `history`
Parameters not published.
Ask AI
Ask AI about io.github.n24q02m/better-telegram-mcp
Powered by Claude · Grounded in docs
Security checks
- ✓README presentThe repository ships documentation.
5 checks have not been run yet.
README
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.
README copy captured when this server was indexed; it may lag the repository. The original is authoritative.