{
"markdown": "# Better Telegram MCP\n\nmcp-name: io.github.n24q02m/better-telegram-mcp\n\n**Telegram for AI agents: messages, chats, media, and contacts in bot and user-account modes.**\n\n\n[](https://github.com/n24q02m/better-telegram-mcp/actions/workflows/ci.yml)\n[](https://codecov.io/gh/n24q02m/better-telegram-mcp)\n[](https://pypi.org/project/better-telegram-mcp/)\n[](https://hub.docker.com/r/n24q02m/better-telegram-mcp)\n[](https://www.apache.org/licenses/LICENSE-2.0)\n\n\n[](#)\n[](https://core.telegram.org)\n[](#)\n[](https://github.com/python-semantic-release/python-semantic-release)\n[](https://github.com/renovatebot/renovate)\n\n\n\n Sister projects from n24q02m (click to expand)
\n\n| Project | Tagline | Tag |\n|---|---|---|\n| [agent-chat-plugin](https://github.com/n24q02m/agent-chat-plugin) | Peer AI agents chat in a shared folder — no human relay, no orchestrator, wor... | Tooling |\n| [better-code-review-graph](https://github.com/n24q02m/better-code-review-graph) | Knowledge graph for token-efficient code reviews -- semantic search and call-... | MCP |\n| [better-drive](https://github.com/n24q02m/better-drive) | 2-way Google Drive sync with .driveignore filter — rclone engine, Windows tray | Tooling |\n| [better-email-mcp](https://github.com/n24q02m/better-email-mcp) | IMAP/SMTP email for AI agents -- read, send, organize folders, and manage att... | MCP |\n| [better-godot-mcp](https://github.com/n24q02m/better-godot-mcp) | Composite MCP server for Godot Engine -- 17 composite tools for AI-assisted g... | MCP |\n| [better-notion-mcp](https://github.com/n24q02m/better-notion-mcp) | Markdown-first Notion for AI agents -- pages, databases, blocks, and comments... | MCP |\n| [better-semantic-release](https://github.com/n24q02m/better-semantic-release) | Drop-in python-semantic-release fork with built-in release-safety guards (orp... | Tooling |\n| [better-telegram-mcp](https://github.com/n24q02m/better-telegram-mcp) | Telegram for AI agents -- messages, chats, media, and contacts across both bo... | MCP |\n| [better-workspace-mcp](https://github.com/n24q02m/better-workspace-mcp) | Google Workspace MCP server (Docs/Drive/Calendar/Gmail/Sheets/Slides/Tasks/Ch... | MCP |\n| [claude-plugins](https://github.com/n24q02m/claude-plugins) | Claude Code plugin marketplace for the n24q02m MCP servers -- install web sea... | Marketplace |\n| [imagine-mcp](https://github.com/n24q02m/imagine-mcp) | Image and video understanding + generation for AI agents -- across Gemini, Op... | MCP |\n| [jules-task-archiver](https://github.com/n24q02m/jules-task-archiver) | Chrome Extension for bulk operations on Jules tasks via batchexecute API -- a... | Tooling |\n| [mcp-core](https://github.com/n24q02m/mcp-core) | Shared foundation for building MCP servers -- Streamable HTTP transport, OAut... | MCP |\n| [mnemo-mcp](https://github.com/n24q02m/mnemo-mcp) | Persistent AI memory with hybrid search and embedded sync. Open, free, unlimi... | MCP |\n| [qwen3-embed](https://github.com/n24q02m/qwen3-embed) | Lightweight Qwen3 text embedding and reranking via ONNX Runtime and GGUF | Library |\n| [skret](https://github.com/n24q02m/skret) | Secrets without the server. | CLI |\n| [tacet](https://github.com/n24q02m/tacet) | A self-distilling neuro-symbolic cascade that amortises LLM cost across knowl... | Tooling |\n| [web-core](https://github.com/n24q02m/web-core) | Shared web infrastructure package for search, scraping, HTTP security, and st... | Library |\n| [wet-mcp](https://github.com/n24q02m/wet-mcp) | Open-source MCP server for AI agents: web search, content extraction, and lib... | MCP |\n\n \n\n\n## Table of contents\n\n- [Features](#features)\n- [Status](#status)\n- [Install](#install)\n- [Smithery](#smithery)\n- [Configuration](#configuration)\n- [CLI](#cli)\n- [Documentation](#documentation)\n- [Tools](#tools)\n- [Comparison](#comparison)\n- [Security](#security)\n- [Build from Source](#build-from-source)\n- [Deploy to Cloudflare](#deploy-to-cloudflare)\n- [Trust Model](#trust-model)\n- [License](#license)\n\n\n\n\n ![\"better-telegram-mcp](\"https://glama.ai/mcp/servers/n24q02m/better-telegram-mcp/badge\")
\n\n\n## Features\n\n- **Dual mode** -- Bot API (httpx) for bots, MTProto (Telethon) for user accounts\n- **7 tools** with action dispatch: `message`, `chat`, `media`, `contact`, `config`, `help`, `config__open_relay`\n- **Auto-detect mode** -- Set bot token for bot mode, or API credentials for user mode\n- **Web-based OTP auth** -- HTTP-mode browser relay form handles phone, OTP, and 2FA for user accounts\n- **Local CLI auth** -- `auth` configures a single-user machine; `login` remains a deprecated alias\n- **Tool annotations** -- Each tool declares `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`\n- **MCP Resources** -- Documentation available as `telegram://docs/*` resources\n- **Security hardened** -- SSRF protection, path traversal prevention, error sanitization\n\n## Status\n\nTwo clean transports: **stdio** (default, local single-user 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](https://mcp.n24q02m.com/get-started/modes-overview/) for the full transport model.\n\nSister MCP servers from the same author are listed in the [collapsible section above](#better-telegram-mcp) -- they share this architecture, so install patterns transfer.\n\n## Install\n\n```bash\n# Method 1 (default): plugin install via Claude Code (stdio, bot mode)\n/plugin marketplace add n24q02m/claude-plugins\n/plugin install better-telegram-mcp@n24q02m-plugins\n\n# Method 1 (CLI): direct uvx invocation (stdio, bot mode)\nclaude mcp add telegram -e TELEGRAM_BOT_TOKEN=123456:ABC-DEF -- uvx better-telegram-mcp\n\n# Method 2 (fallback): Docker stdio\ndocker run -i --rm -e TELEGRAM_BOT_TOKEN=123456:ABC-DEF n24q02m/better-telegram-mcp\n\n# Method 3 (recommended for user mode / multi-device / OAuth): Docker HTTP\ndocker run -d --name better-telegram-mcp-http -p 8080:8080 \\\n -e MCP_TRANSPORT=http \\\n -e PUBLIC_URL=https://telegram.example.com \\\n -e MCP_DCR_SERVER_SECRET=<32+ random bytes> \\\n n24q02m/better-telegram-mcp:latest\n```\n\nStdio mode is local single-user mode. Bot mode uses `TELEGRAM_BOT_TOKEN`; user mode\ncan be configured locally with `better-telegram-mcp auth --phone <+number>`. HTTP\nuser mode uses the browser-based relay form at `/authorize` for phone, OTP, and 2FA.\n\n**Remote endpoint** -- an HTTP deployment is OAuth-gated and serves `/mcp`. Point any\nMCP client that speaks Streamable HTTP + OAuth 2.1 at `https:///mcp`; each\nuser completes the browser relay setup (bot token, or phone + OTP) on first connect.\nTo run one, use the Docker HTTP method above or the\n[Cloudflare deploy](#deploy-to-cloudflare) below.\n\nFull setup matrices live at the canonical docs site\n[mcp.n24q02m.com/servers/better-telegram-mcp/setup/](https://mcp.n24q02m.com/servers/better-telegram-mcp/setup/),\nand the paste-to-agent snippets at\n[claude-plugins/plugins/better-telegram-mcp/setup-with-agent.md](https://github.com/n24q02m/claude-plugins/blob/main/plugins/better-telegram-mcp/setup-with-agent.md).\n\n## Smithery\n\nAlso listed on [Smithery](https://smithery.ai/servers/n24q02m/better-telegram-mcp).\nPer [`smithery.yaml`](smithery.yaml), Smithery starts the server over **stdio** with\n`uvx --python 3.13 better-telegram-mcp` and takes **no install-time configuration**\n(empty `configSchema`) -- credentials are provided at runtime through the server's own\nsetup flow: the `TELEGRAM_BOT_TOKEN` env var or local `auth` command for stdio\nsingle-user mode, or the browser relay form for HTTP user mode (see\n[Configuration](#configuration)).\n\n## Configuration\n\nSettings load from `TELEGRAM_`-prefixed environment variables (Pydantic Settings).\n\n**Stdio mode (local single-user):**\n\n| Variable | Required | Description |\n|:---------|:---------|:------------|\n| `TELEGRAM_BOT_TOKEN` | Yes | Bot token from [@BotFather](https://t.me/BotFather) (format `123456789:ABCdef...`) |\n\n**HTTP mode (bot + user):** credentials are entered via the browser relay form,\nnot env vars. Server-side env vars for self-hosting:\n\n| Variable | Required | Default | Description |\n|:---------|:---------|:--------|:------------|\n| `MCP_TRANSPORT` | Yes | `stdio` | Set to `http` to enable HTTP mode (`--http` CLI flag or `TRANSPORT_MODE=http` also work) |\n| `PUBLIC_URL` | Self-host | -- | Public URL of the server; presence enables the multi-user OAuth branch |\n| `MCP_DCR_SERVER_SECRET` | Self-host | -- | Multi-user OAuth shared secret, 32+ random bytes (legacy `DCR_SERVER_SECRET` still accepted) |\n| `HOST` | No | `0.0.0.0` | Bind address |\n| `PORT` | No | `8080` | HTTP port |\n\n**User-mode credentials (optional overrides):** `TELEGRAM_API_ID` and\n`TELEGRAM_API_HASH` ship with built-in public dev defaults, so only\n`TELEGRAM_PHONE` is needed to start the phone + OTP flow. `TELEGRAM_SESSION_NAME`\nand `TELEGRAM_DATA_DIR` customize the Telethon session file location. There is no\n`TELEGRAM_PASSWORD` env var -- HTTP relay 2FA is entered through the web UI; local\nCLI auth prompts interactively and never stores it in the environment.\n\n## CLI\n\nThe `better-telegram-mcp` console script (installed by `uvx` / `pip`) **starts the\nserver** when run with no subcommand, and exposes a few operator subcommands for local\nsingle-user setup and diagnostics. Any flag that is not a subcommand is passed straight\nthrough to the server (e.g. `--http`).\n\n```bash\nbetter-telegram-mcp # start the MCP server (stdio, bot mode by default)\nbetter-telegram-mcp --http # start in HTTP mode\nbetter-telegram-mcp --version # print the version\n```\n\n**Subcommands** (`better-telegram-mcp `):\n\n| Subcommand | Usage | Description |\n|:-----------|:------|:------------|\n| `auth` | `auth --bot-token ` or `auth --phone <+number>` | Authenticate this machine (single-user). Bot mode validates the token; phone mode runs the interactive OTP/2FA flow and stores the Telethon session on disk |\n| `login` | Same arguments as `auth` | Deprecated alias of `auth` |\n| `logout` | `logout` | Revoke the Telegram session server-side, delete the local session file, and clear saved credentials |\n| `config` | `config status`, `config delete [--yes]` | Show or delete the saved local credential config (env overrides still take precedence at server start) |\n| `relay` | `relay status`, `relay open`, `relay reset` | Inspect, open (print a fresh setup URL for), or reset the browser relay setup session |\n| `doctor` | `doctor` | Print environment diagnostics -- Python version, credential backend, config + relay state, and transport mode |\n\n```bash\n# Bot mode: validate a bot token and save it to the local config\nbetter-telegram-mcp auth --bot-token 123456:ABC-DEF\n\n# User mode: interactive phone + OTP (+ 2FA if enabled) sign-in\nbetter-telegram-mcp auth --phone +15551234567\n\n# Remove local credentials and revoke the session\nbetter-telegram-mcp logout\n```\n\nThe `auth` command, its deprecated `login` alias, and `logout` are single-user and local-machine only -- they write\nthe on-disk Telethon session and the encrypted single-user config, so run them on the\nmachine that hosts the stdio server. For remote / multi-user HTTP deployments,\ncredentials are entered through the browser relay form instead (see the\n[remote endpoint](#install) and [Configuration](#configuration)).\n\n## Documentation\n\nFull docs at **[mcp.n24q02m.com/servers/better-telegram-mcp/setup/](https://mcp.n24q02m.com/servers/better-telegram-mcp/setup/)**:\n\n- [Setup](https://mcp.n24q02m.com/servers/better-telegram-mcp/setup/) -- install methods for Claude Code, Codex, Gemini CLI, Cursor, Windsurf, mcp.json\n- [Modes overview](https://mcp.n24q02m.com/get-started/modes-overview/) -- stdio (local, single-user) and HTTP (remote, OAuth 2.1)\n- [Multi-user setup](https://mcp.n24q02m.com/get-started/multi-user/) -- per-JWT-sub credential model\n\n**Install with AI agent** -- paste this to your AI coding agent:\n\n> Install MCP server `better-telegram-mcp` following the steps at\n> https://raw.githubusercontent.com/n24q02m/claude-plugins/main/plugins/better-telegram-mcp/setup-with-agent.md\n\n## Tools\n\n| Tool | Actions | Description |\n|:-----|:--------|:------------|\n| `message` | `send`, `edit`, `delete`, `forward`, `pin`, `react`, `search`, `history` | Send, edit, delete, forward messages. Pin, react, search, browse history |\n| `chat` | `list`, `info`, `create`, `join`, `leave`, `members`, `admin`, `settings`, `topics` | List and manage chats, groups, channels. Members, admin, forum topics |\n| `media` | `send_photo`, `send_file`, `send_voice`, `send_video`, `download` | Send photos, files, voice notes, videos. Download media from messages |\n| `contact` | `list`, `search`, `add`, `block` | List, search, add contacts. Block/unblock users (user mode only) |\n| `config` | `status`, `set`, `cache_clear`, `setup_status`, `setup_start`, `setup_reset`, `setup_complete` | Server status, runtime settings, cache, credential setup (relay, status, reset, complete) |\n| `help` | -- | Full documentation for any topic |\n| `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 |\n\n### MCP Resources\n\n| URI | Content |\n|:----|:--------|\n| `telegram://docs/messages` | Message operations reference |\n| `telegram://docs/chats` | Chat management reference |\n| `telegram://docs/media` | Media send/download reference |\n| `telegram://docs/contacts` | Contact management reference |\n| `telegram://stats` | All documentation combined |\n\n## Comparison\n\nHow better-telegram-mcp stacks up against direct competitors in each pillar:\n\n| Capability | better-telegram-mcp | chigwell/telegram-mcp | sparfenyuk/mcp-telegram | guangxiangdebizi/telegram-mcp |\n|---|---|---|---|---|\n| Bot API mode (bot token) | Yes (httpx) | No | No | Yes |\n| MTProto user-account mode | Yes (Telethon) | Yes | Yes | No |\n| Send / edit / delete messages | Yes | Yes | No (read-only, draft only) | Yes (send only) |\n| Media download from messages | Yes | Yes | Yes | No (send only) |\n| Contact management (add / block) | Yes (user mode) | Yes | Partial (list only) | No |\n| Web-based / browser OTP auth | Yes (relay form, headless) | No (CLI session string) | No (CLI sign-in) | No (pre-set bot token) |\n| Multi-user remote, per-user isolation | Yes (per-JWT-sub backends) | No | No | No |\n| SSRF protection | Yes (URL validation + DNS-rebinding) | ? | ? | No |\n| Path-traversal prevention | Yes | Yes (real-path allowed-root) | ? | No |\n| Self-hostable | Yes | Yes | Yes | Yes |\n\n## Security\n\n- **SSRF Protection** -- All URLs validated against internal/private IP ranges, DNS rebinding blocked\n- **Path Traversal Prevention** -- File paths validated, sensitive directories blocked\n- **Session File Security** -- 600 permissions, 2FA via web UI only (never stored in env vars)\n- **Error Sanitization** -- Credentials never leaked in error messages\n\n## Build from Source\n\n```bash\ngit clone https://github.com/n24q02m/better-telegram-mcp.git\ncd better-telegram-mcp\nuv sync\nuv run better-telegram-mcp\n```\n\n## Deploy to Cloudflare\n\n[](https://deploy.workers.cloudflare.com/?url=https://github.com/n24q02m/better-telegram-mcp)\n\nRun your own multi-user better-telegram-mcp serverless on Cloudflare (Worker + Container + KV).\n\n**Prerequisites:** a Cloudflare account on the **Workers Paid plan** -- required for Containers (the Cloudflare free tier does not include Containers) -- and the `wrangler` CLI.\n\n1. `git clone https://github.com/n24q02m/better-telegram-mcp && cd better-telegram-mcp`\n2. `wrangler login`\n3. Provision the KV namespace and paste its id into `wrangler.jsonc`:\n ```\n wrangler kv namespace create better-telegram-kv\n ```\n4. Push the container image to your Cloudflare managed registry (CF Containers cannot\n pull from external registries directly), then set `` in `wrangler.jsonc`:\n ```\n docker pull ghcr.io/n24q02m/better-telegram-mcp:beta\n docker tag ghcr.io/n24q02m/better-telegram-mcp:beta better-telegram-mcp:beta\n wrangler containers push better-telegram-mcp:beta # prints registry.cloudflare.com//better-telegram-mcp:beta\n ```\n5. Set `` (e.g. `https://telegram.example.com`) and ``\n (e.g. `telegram.example.com`) in `wrangler.jsonc`, then set secrets:\n ```\n wrangler secret put CREDENTIAL_SECRET\n wrangler secret put MCP_RELAY_PASSWORD\n wrangler secret put MCP_DCR_SERVER_SECRET\n ```\n `CREDENTIAL_SECRET` is REQUIRED: it derives a deterministic OAuth signing key so\n user identity survives container recreation. `MCP_RELAY_PASSWORD` gates the browser\n setup form (Gate A shared front door); `MCP_DCR_SERVER_SECRET` (32+ random bytes)\n marks the deploy as intentionally multi-user.\n6. `wrangler deploy`, then complete setup in the browser relay form at your Worker domain --\n each user enters their own bot token or phone + OTP there, so no per-user Telegram\n credentials live on the Worker.\n\nStorage maps to Cloudflare via `MCP_STORAGE_BACKEND=cf-kv` (the encrypted setup config).\nDo NOT set `MCP_AUTH_DISABLE` on a shared/public deployment -- it collapses all users\ninto a single credential bucket.\n\n## Trust Model\n\nThis plugin implements **TC-NearZK** (in-memory, ephemeral). See [mcp-core trust model](https://mcp.n24q02m.com/servers/mcp-core/trust-model/) for full classification.\n\nThe project no longer operates an n24q02m-hosted Telegram endpoint. HTTP mode is available only on infrastructure an operator deploys and controls.\n\n| Mode | Storage | Encryption | Who can read your data? |\n|---|---|---|---|\n| HTTP self-host (opt-in) | In-memory `dict[sub] = MTProtoSession` | In-process only | Operator-controlled server process (cleared on restart) |\n| stdio | `~/.config/mcp/config.enc` (credentials) + `~/.better-telegram-mcp/.session` (Telethon session) | AES-GCM, machine-bound key | Only your OS user (file perm 0600) |\n\n### Workspace username (HTTP setup form)\n\nThe browser setup form has an optional **workspace username** field. Entering the\nsame username always lands you in the same per-`sub` bucket, so your session stays\nreachable across a re-authorization and across devices, instead of being tied to\nthe one-off subject minted for each `/authorize` round-trip. Leaving it blank\nkeeps the previous per-authorize behaviour.\n\nTrust boundary: when the form is gated by a *shared* `MCP_RELAY_PASSWORD`, the\nusername is a partition key, not a secret -- anyone who knows that password can\ntype any username and reach that bucket. That is fine for a trusted group; an\nuntrusted multi-tenant deployment needs a per-user secret or delegated OAuth\ninstead.\n\n**One-time migration:** existing users must re-authenticate once after this\nchange. Nothing is deleted; sessions stored under the old random subject are\nsimply no longer addressed.\n\n## License\n\nApache-2.0 -- See [LICENSE](LICENSE).\n",
"bytes": 20359,
"sha": "93b19471c648f53219166d188c6cdd5996f5dcb5141114c261031ebddee9ea47",
"repo_slug": "n24q02m/better-telegram-mcp",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_n24q02m_better_telegram_mcp_806de366/readme"
}