Better Telegram Mcp

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.

[](https://github.com/n24q02m/better-telegram-mcp/actions/workflows/ci.yml) [](https://codecov.io/gh/n24q02m/better-telegram-mcp) [](https://pypi.org/project/better-telegram-mcp/) [](https://hub.docker.com/r/n24q02m/better-telegram-mcp) [](https://opensource.org/licenses/MIT)

[](#) [](https://core.telegram.org) [](#) [](https://github.com/python-semantic-release/python-semantic-release) [](https://github.com/renovatebot/renovate)

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](#features)
• [Status](#status)
• [Install](#install)
• [Configuration](#configuration)
• [Documentation](#documentation)
• [Tools](#tools)
• [Comparison](#comparison)
• [Security](#security)
• [Build from Source](#build-from-source)
• [Trust Model](#trust-model)
• [License](#license)

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 -- HTTP-mode browser relay form handles phone, OTP, and 2FA for user accounts (no session strings, no CLI sign-in)
• 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

Two clean transports: stdio (default, bot mode) and HTTP (bot + user mode, browser relay setup, optional multi-user). No daemon-bridge layer and no auto-spawn from stdio. See Modes overview for the full transport model.

Sister MCP servers from the same author are listed in the [collapsible section above](#better-telegram-mcp) -- they share this architecture, so install patterns transfer.

Install

# Method 1 (default): plugin install via Claude Code (stdio, bot mode)
/plugin marketplace add n24q02m/claude-plugins
/plugin install better-telegram-mcp@n24q02m-plugins

# Method 1 (CLI): direct uvx invocation (stdio, bot mode)
claude mcp add telegram -e TELEGRAM_BOT_TOKEN=123456:ABC-DEF -- uvx better-telegram-mcp

# Method 2 (fallback): Docker stdio
docker run -i --rm -e TELEGRAM_BOT_TOKEN=123456:ABC-DEF n24q02m/better-telegram-mcp

# Method 3 (recommended for user mode / multi-device / OAuth): Docker HTTP
docker run -d --name better-telegram-mcp-http -p 8080:8080 \
  -e MCP_TRANSPORT=http \
  -e PUBLIC_URL=https://telegram.example.com \
  -e MCP_DCR_SERVER_SECRET= \
  n24q02m/better-telegram-mcp:latest

Stdio mode is bot mode only (TELEGRAM_BOT_TOKEN). User mode (full account via phone + OTP) runs in HTTP mode, where credentials are entered through the browser-based relay form at /authorize.

Full setup matrices live at the canonical docs site mcp.n24q02m.com/servers/better-telegram-mcp/setup/, and the paste-to-agent snippets at claude-plugins/plugins/better-telegram-mcp/setup-with-agent.md.

Configuration

Settings load from TELEGRAM_-prefixed environment variables (Pydantic Settings).

Stdio mode (bot only):

| Variable | Required | Description | |:---------|:---------|:------------| | TELEGRAM_BOT_TOKEN | Yes | Bot token from @BotFather (format 123456789:ABCdef...) |

HTTP mode (bot + user): credentials are entered via the browser relay form, not env vars. Server-side env vars for self-hosting:

| Variable | Required | Default | Description | |:---------|:---------|:--------|:------------| | MCP_TRANSPORT | Yes | stdio | Set to http to enable HTTP mode (--http CLI flag or TRANSPORT_MODE=http also work) | | PUBLIC_URL | Self-host | -- | Public URL of the server; presence enables the multi-user OAuth branch | | MCP_DCR_SERVER_SECRET | Self-host | -- | Multi-user OAuth shared secret, 32+ random bytes (legacy DCR_SERVER_SECRET still accepted) | | HOST | No | 0.0.0.0 | Bind address | | PORT | No | 8080 | HTTP port |

User-mode credentials (optional overrides): TELEGRAM_API_ID and TELEGRAM_API_HASH ship with built-in public dev defaults, so only TELEGRAM_PHONE is needed to start the phone + OTP flow. TELEGRAM_SESSION_NAME and TELEGRAM_DATA_DIR customize the Telethon session file location. There is no TELEGRAM_PASSWORD env var -- 2FA is entered through the web UI and never stored in the environment.

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/.session (Telethon session) | AES-GCM, machine-bound key | Only your OS user (file perm 0600) |

License

MIT -- See [LICENSE](LICENSE).

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: n24q02m
• Source: n24q02m/better-telegram-mcp
• License: MIT
• Homepage: https://mcp.n24q02m.com/servers/better-telegram-mcp/

Install and usage instructions live in the source repository linked above.