
<!-- Created: Saturday, November 21, 2026, 1:32 AM PST -->
<!-- Modified: Saturday, November 21, 2026, 11:28 AM PST -->

For founders, investors, and distributed engineering teams, half of real work happens in Telegram. Links, PDF decks, vendor quotes, and quick decisions land in chat threads days before they reach email. Naturally, people want their local AI agent inside Claude Code, Cursor, or Antigravity CLI to search those chats and pull attachments into working notes.

Telegram's wire protocol turns that convenience into a severe security trap. Unlike Gmail, Slack, or GitHub, Telegram's MTProto user API offers no read-only OAuth scope. Every authenticated user session holds the same authority as a logged-in phone. Installing a general-purpose Telegram MCP wrapper gives both a large third-party dependency tree and a language model full permission to message contacts, delete history, forward private threads, and inspect your security alerts.

To solve that without giving up chat context, I built and open-sourced [tgread](https://github.com/wjkoh/tgread) under the Apache 2.0 license. It is a minimal, pure-Go Telegram MCP server and CLI that enforces its read-only boundary at compile time rather than in a prompt.

## Why Prompt Rules and Tool Hints Fail

Picture a routine workflow. You ask your coding agent to scan an unread group chat, pull a forwarded PDF report, and summarize the key numbers into a memo. Buried inside a spam message or a document caption sits a prompt injection instructing the model to message a contact or forward a verification code.

Most community Telegram MCP servers wrap Python or Node MTProto clients such as Telethon or GramJS and register write tools alongside search. Asking the model in a system prompt to avoid write calls, or trusting MCP client annotations such as `readOnlyHint`, turns access control into an honor system. As long as send, delete, or forward tools exist in the running server, an injected payload can still persuade the model to invoke them.

Even a server that skips write tools leaves one dangerous loophole open. Telegram delivers one-time login codes and new-device alerts through its official service account, user ID 777000. Any agent allowed to list and read every chat can read a fresh login code triggered by an attacker attempting to link a new device to your account.

## Enforcing Least Privilege at Compile Time

When an upstream protocol refuses to issue scoped credentials, the only reliable boundary lives inside the binary you compile and run. Instead of filtering writes at runtime inside a sprawling scripting stack, tgread eliminates mutation capabilities before the binary exists and hardens the surrounding read surface:

| Threat Surface | Compile-Time and Runtime Control in tgread |
| :--- | :--- |
| **Account Mutation** | Zero write, send, edit, delete, or forward RPCs exist in the codebase. An automated Go test named `TestReadOnlyASTAudit` parses every non-test source file with `go/ast`, bans Telegram mutation method prefixes across the codebase, and restricts direct client calls to an eight-method read-only allowlist. |
| **Unread State Pollution** | Read-receipt RPCs are absent from the allowlist. Your agent can inspect recent threads without clearing unread badges on your phone or desktop. |
| **Login-Code Theft** | Service account 777000 is blocked by default across chat listing, message history, global search, and attachment downloads unless explicitly enabled via `--allow-telegram-service-chat`. |
| **Supply-Chain Bloat** | Only two direct external Go modules enter the build, `gotd/td` for MTProto and `modelcontextprotocol/go-sdk` for MCP stdio framing, compiled with `CGO_ENABLED=0` into one static binary. |
| **Credential and Disk Leaks** | API credentials load from mounted secret files via `--api-id-file` and `--api-hash-file`, keeping raw secrets out of MCP JSON configs and process environments. Attachments download on demand into a mode 0700 cache with sanitized names, atomic renames, SHA-256 digests, and a 50 MB default cap. |

The AST check is intentionally blunt. Every direct call on the Telegram API client must belong to eight read methods: `UsersGetUsers`, `MessagesGetDialogs`, `MessagesGetHistory`, `MessagesSearch`, `MessagesSearchGlobal`, `MessagesGetMessages`, `ChannelsGetMessages`, and `ContactsResolveUsername`. Any accidental reference to a send, edit, delete, pin, or read-receipt method breaks `go test` and CI immediately.

Read-only tools still fail in practice if they mangle message content. Telegram encodes hidden hyperlinks using UTF-16 code-unit offsets rather than UTF-8 byte indices, so naive parsers split emoji and Korean or Chinese text at the wrong boundary and drop links. tgread decodes UTF-16 entities cleanly, extracts web preview cards, resolves your outgoing messages to your display name rather than Saved Messages, and fetches grouped media albums in one call.

Getting started takes one static binary and a QR scan from Telegram's linked-devices menu:

```bash
go install github.com/wjkoh/tgread/cmd/tgread@latest
tgread login --qr --api-id-file /run/secrets/telegram/api_id --api-hash-file /run/secrets/telegram/api_hash
tgread chats --unread
```

Registering `tgread serve` as an MCP server exposes four read-only tools: `list_chats`, `get_messages`, `search_messages`, and `download_attachment`. Because the CLI and MCP server share the same access policy layer, optional `--allow-chats` and `--deny-chats` filters behave identically whether you run a shell command or query from an agent.

## What Compile-Time Read-Only Cannot Solve

Removing write RPCs from the Telegram server eliminates direct account abuse, yet three real boundaries remain:

1. **Cross-Tool Exfiltration Still Exists:** A read-only Telegram server cannot send a Telegram message, yet a hostile prompt embedded inside an incoming chat can still coax the same agent session into leaking chat text through a separate Gmail, Slack, or shell tool. Pair read-only messaging inputs with human approval on outbound write tools, and restrict broad chat scanning with `--allow-chats` or `--deny-chats` when working with untrusted groups.
2. **Host Compromise Bypasses the Binary:** The authenticated session stored at `~/.config/tgread/session.json` with mode 0600 still holds a real MTProto authorization key. If malware compromises your local workstation and reads that file, it can talk directly to Telegram's servers without going through tgread.
3. **Secret Chats Remain Invisible:** Telegram Secret Chats use device-bound end-to-end encryption and never synchronize to secondary MTProto sessions. Cloud direct messages, Saved Messages, groups, supergroups, and channels all work; Secret Chats stay off-limits by protocol design.

AI agents are only as safe as the narrowest capability compiled into their tools. When a messaging platform refuses to give users scoped tokens, the answer is not a sterner system prompt. Strip the dangerous verbs out of the binary, audit the syntax tree in CI, and let your agent read without giving it the keys to speak for you.

The full design document, AST audit test, and Apache 2.0 source code live at [github.com/wjkoh/tgread](https://github.com/wjkoh/tgread).

