Skip to content
Back to search

telegram-mcp

Read-only Telegram MCP server built with Python and TDLib

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/whytrall--telegram-mcp/badge.svg)](/listings/whytrall--telegram-mcp)

HTML

<a href="/listings/whytrall--telegram-mcp"><img src="/api/listings/whytrall--telegram-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

curl -fsSL https://raw.githubusercontent.com/whytrall/telegram-mcp/refs/heads/master/install.sh | bash

Requires **Python 3.11+**, Git, and curl

Or, even a lazier version, paste this to your agent:

Install MCP server from https://github.com/whytrall/telegram-mcp

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 121 lines · 1 finding marked
  1. # Telegram MCP
  2. An MCP server for Telegram based on TDLib, with read tools and confirmed message sending
  3. Important note: you should be careful when using third-party Telegram clients,
  4. including this one. Check the source code before signing in, or, in current realities,
  5. ask your AI agent to check the code to make sure that I'm not trying to steal your messages
  6. No guarantees: this MCP server works for me, so it *might* work for you
  7. ## Installation
  8. ```sh
  9. curl -fsSL https://raw.githubusercontent.com/whytrall/telegram-mcp/refs/heads/master/install.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 14 on GitHub
  10. ```
  11. Requires **Python 3.11+**, Git, and curl
  12. Or, even a lazier version, paste this to your agent:
  13. ```
  14. Install MCP server from https://github.com/whytrall/telegram-mcp
  15. ```
  16. ## Tools
  17. Read tools carry MCP read-only annotations and use an explicit allowlist
  18. of TDLib methods. They automatically start browser authentication if needed.
  19. The `logout` tool changes authentication state and is annotated accordingly.
  20. `send_message` sends text, photos, videos, and files. **Do not use it without explicit
  21. user confirmation** of the recipient, content, and attachments; it requires `confirmed=true`.
  22. Attachments use an absolute local `path` and `type` (`photo`, `video`, or `file`).
  23. Up to 10 photos/videos or 10 files can be grouped; files and photos/videos cannot mix.
  24. Text is the first attachment's caption, or a standalone message when no attachments are given.
  25. Videos must already be MP4/H.264. A `pending` result means upload/delivery is still
  26. in progress. Check message history before retrying an uncertain send to avoid duplicates.
  27. Pending sends keep the backend alive until TDLib reports success or failure, so idle
  28. shutdown does not interrupt an upload.
  29. Restrict both reading and sending to specific chats by setting this in the MCP
  30. server's environment (or its explicit `--env-file`):
  31. ```sh
  32. TELEGRAM_ALLOWED_CHAT_IDS=42,-1001234567890
  33. ```
  34. Use the numeric TDLib IDs returned by `list_chats` or `get_chat`. Unset means all
  35. chats; an explicitly empty value blocks all chats. Invalid values stop startup.
  36. Direct reads, topics, replies, and sends reject other chats; chat listings/search
  37. results include only allowed chats. Message search must specify an allowed
  38. `chat_id`; global message search, username resolution, and arbitrary `get_user`
  39. lookups are disabled while restrictions are configured. Account identity, status,
  40. and logout remain available. `telegram_status` reports the effective allowlist.
  41. All clients sharing `TELEGRAM_DATA_DIR` must use the same allowlist. After changing
  42. it, stop the shared backend and restart the MCP connections; a mismatched client
  43. is rejected instead of reusing a backend with different permissions. Reinstalling
  44. preserves existing server environment settings and `--env-file` arguments.
  45. The restriction controls MCP access, while TDLib still synchronizes the account locally.
  46. There is no raw TDLib request tool.
  47. | Tool | Purpose |
  48. | --- | --- |
  49. | `telegram_status` | Check whether the saved session is authorized |
  50. | `logout` | Revoke the shared Telegram session and clear TDLib's local account cache |
  51. | `send_message` | Send confirmed text, photos, videos, or files; supports topics and replies |
  52. | `get_me` | Current user's profile |
  53. | `get_user` | Profile for a message sender's user ID |
  54. | `list_chats` | First main/archive chats with unread counts and last messages |
  55. | `search_chats` | Find account chats by title/username using server-backed search |
  56. | `resolve_username` | Resolve a public @username without joining |
  57. | `get_chat` | Chat details and last message |
  58. | `list_topics` | Sidebar topics in forum groups and private bot chats, with name search and paging |
  59. | `get_history` | Newest-first chat or sidebar topic history; pass `forum_topic_id` from `list_topics` |
  60. | `get_message` | One message by TDLib IDs |
  61. | `search_messages` | Global or chat-specific text search with paging |
  62. ## Details
  63. The installer creates `.venv` inside the download and sets the
  64. user-level `telegram` server in `~/.claude.json` and `~/.codex/config.toml`
  65. (`CODEX_HOME` is respected). It replaces an existing `telegram` entry and keeps
  66. other servers and settings. Restart Claude Code and Codex afterward; your first
  67. account read opens the browser login page. No Telegram credentials go in the command.
  68. To update an existing installation, rerun the same command, then stop the shared backend
  69. with `~/.local/trl-telegram-mcp/.venv/bin/telegram-mcp stop` and restart the clients.
  70. For custom config locations,
  71. pass `--claude-config /path/to/claude.json --codex-config /path/to/config.toml` to that script.
  72. For development, clone the repository and install from its root:
  73. ```sh
  74. python3.13 -m venv .venv
  75. .venv/bin/python -m pip install -e '.[dev]'
  76. ```
  77. On macOS 13+, that is enough: the server uses the bundled library. To rebuild the
  78. universal macOS binary from pinned sources (Xcode Command Line Tools, Git, Perl,
  79. CMake, and gperf are required):
  80. ```sh
  81. brew install cmake gperf
  82. bash scripts/prebuild_tdlib_macos.sh
  83. ```
  84. This builds both architectures with a macOS 13 deployment target, links OpenSSL
  85. statically, and writes `src/telegram_mcp/_vendor/macos/libtdjson.dylib`. The adjacent
  86. manifest records the TDLib commit, OpenSSL version, architectures, and SHA-256;
  87. license files are included. Build products and downloaded sources stay in `.deps/`.
  88. `TDLIB_BUILD_JOBS` controls parallelism (default 8 for the prebuild script).
  89. On Debian/Ubuntu, build TDLib locally (C++ compiler, Git, CMake, gperf, OpenSSL,
  90. and zlib are required):
  91. ```sh
  92. sudo apt-get install build-essential git cmake gperf libssl-dev zlib1g-dev
  93. bash scripts/build_tdlib.sh
  94. export TDLIB_LIBRARY_PATH="$PWD/.deps/td-build/libtdjson.so"
  95. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.