Skip to content
Back to search

tgread

Minimal, compile-time read-only Telegram MTProto CLI and MCP server in Go

Safety scan

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

Checked today

Check it deeper on your machine

It has changed since its scan on 21 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/wjkoh/tgread with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/wjkoh/tgread'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/wjkoh--tgread/badge.svg)](/listings/wjkoh--tgread)

HTML

<a href="/listings/wjkoh--tgread"><img src="/api/listings/wjkoh--tgread/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.

1. Get Telegram API credentials

Create an app at https://my.telegram.org/apps to obtain `API_ID` and `API_HASH`.

2. One-time interactive login

Scan a QR code directly in Telegram (**Settings → Devices → Link Desktop Device**):

tgread login --qr \
  --api-id-file /run/secrets/telegram/api_id \
  --api-hash-file /run/secrets/telegram/api_hash

Or use phone number + login code:

export TGREAD_API_ID=12345678
export TGREAD_API_HASH=your_api_hash
tgread login

This authenticates your session and stores it at `~/.config/tgread/session.json` with `0600` permissions.

Verify authorization:

tgread status
tgread chats --unread

3. Register with Antigravity CLI (`~/.gemini/config/mcp_config.json`)

Standard env-var configuration:

{
  "mcpServers": {
    "tgread": {
      "command": "/Users/you/.local/bin/tgread",
      "args": ["serve"],
      "env": {
        "TGREAD_API_ID": "12345678",
        "TGREAD_API_HASH": "your_api_hash"
      }
    }
  }
}

Or declaratively with Nix-Darwin + SOPS-Nix (zero raw credentials in `mcp_config.json` or process env):

{
  "mcpServers": {
    "tgread": {
      "command": "/nix/store/...-tgread-0.1.0/bin/tgread",
      "args": [
        "serve",
        "--api-id-file", "/run/secrets/telegram/api_id",
        "--api-hash-file", "/run/secrets/telegram/api_hash"
      ]
    }
  }
}

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. # tgread
  2. Created: Friday, November 20, 2026 — 14:53 PST
  3. License: Apache-2.0
  4. A minimal, compile-time read-only Telegram MTProto MCP server and CLI written in pure Go.
  5. Built for local AI agents (Antigravity CLI, Claude Code, Cursor) to read received Telegram messages, hidden hyperlinks, link previews, and attached PDFs or images without giving a third-party MCP wrapper write access to your personal account.
  6. ## Security Guarantees
  7. 1. **Minimal dependency tree:** Only two direct external Go modules (`github.com/gotd/td` and `github.com/modelcontextprotocol/go-sdk`), zero CGO, static binary.
  8. 2. **Compile-time read-only:** Zero write, send, edit, delete, or read-receipt Telegram RPCs exist anywhere in the binary. Unread badges on your phone and desktop remain untouched. An automated Go AST audit test (`TestReadOnlyASTAudit`) fails the build if any Telegram mutation RPC is introduced.
  9. 3. **Login-code protection by default:** Telegram's official service account (`777000`, where OTP login codes arrive) is blocked across all listing, history, search, and download operations unless explicitly enabled via `--allow-telegram-service-chat`.
  10. 4. **Optional allowlist and denylist:** Reads all standard cloud chats by default, with optional `--allow-chats` and `--deny-chats` filtering by numeric chat ID or `@username`.
  11. 5. **Safe attachment downloads:** Attachments download on demand into a `0700` local cache directory with sanitized filenames, path-traversal checks, atomic temp-file writes, SHA-256 digests, and a default 50 MB size limit.
  12. > **Note on Secret Chats:** Telegram Secret Chats use device-bound end-to-end encryption and cannot be read from any secondary MTProto session. Standard cloud DMs, Saved Messages (`me`), groups, supergroups, and channels all work.
  13. ## Build & Install
  14. With Nix + Go-Task:
  15. ```bash
  16. direnv allow
  17. direnv exec . task check
  18. direnv exec . task install
  19. ```
  20. Or with standard Go:
  21. ```bash
  22. CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o ~/.local/bin/tgread ./cmd/tgread
  23. ```
  24. ## Quickstart
  25. ### 1. Get Telegram API credentials
  26. Create an app at https://my.telegram.org/apps to obtain `API_ID` and `API_HASH`.
  27. ### 2. One-time interactive login
  28. Scan a QR code directly in Telegram (**Settings → Devices → Link Desktop Device**):
  29. ```bash
  30. tgread login --qr \
  31. --api-id-file /run/secrets/telegram/api_id \
  32. --api-hash-file /run/secrets/telegram/api_hash
  33. ```
  34. Or use phone number + login code:
  35. ```bash
  36. export TGREAD_API_ID=12345678
  37. export TGREAD_API_HASH=your_api_hash
  38. tgread login
  39. ```
  40. This authenticates your session and stores it at `~/.config/tgread/session.json` with `0600` permissions.
  41. Verify authorization:
  42. ```bash
  43. tgread status
  44. tgread chats --unread
  45. ```
  46. ### 3. Register with Antigravity CLI (`~/.gemini/config/mcp_config.json`)
  47. Standard env-var configuration:
  48. ```json
  49. {
  50. "mcpServers": {
  51. "tgread": {
  52. "command": "/Users/you/.local/bin/tgread",
  53. "args": ["serve"],
  54. "env": {
  55. "TGREAD_API_ID": "12345678",
  56. "TGREAD_API_HASH": "your_api_hash"
  57. }
  58. }
  59. }
  60. }
  61. ```
  62. Or declaratively with Nix-Darwin + SOPS-Nix (zero raw credentials in `mcp_config.json` or process env):
  63. ```json
  64. {
  65. "mcpServers": {
  66. "tgread": {
  67. "command": "/nix/store/...-tgread-0.1.0/bin/tgread",
  68. "args": [
  69. "serve",
  70. "--api-id-file", "/run/secrets/telegram/api_id",
  71. "--api-hash-file", "/run/secrets/telegram/api_hash"
  72. ]
  73. }
  74. }
  75. }
  76. ```
  77. ## Exposed MCP Tools (All `readOnlyHint: true`)
  78. | Tool | Description |
  79. | --- | --- |
  80. | `list_chats` | List recent cloud chats, groups, channels, and Saved Messages with unread counts and previews |
  81. | `get_messages` | Fetch recent messages with resolved sender names, UTF-16-accurate hidden URLs, web preview cards, and attachment metadata |
  82. | `search_messages` | Search inside one chat or globally across allowed chats with optional media filters (`photos`, `documents`, `urls`, `audio`, `voice`, `video`) |
  83. | `download_attachment` | Download a PDF, photo, audio note, or grouped album (`include_album: true`) into the local cache and return paths + SHA-256 hashes |
  84. ## Direct CLI Usage
  85. ```bash
  86. tgread chats --limit 20 --unread
  87. tgread messages --chat me --limit 10
  88. tgread search --query "invoice" --filter documents
  89. tgread download --chat -1001234567890 --message-id 42 --album
  90. ```

Ratings and comments

Sign in to rate this skill.

Sign in

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