Postun — open-source Telegram MCP server: connect your own Telegram to ChatGPT, Claude and Claude Code, in transit, with no message storage

English · Русский · Español · Português · Deutsch

The English README is canonical; translations follow it and may lag behind.

Postun Beta is an open-source MCP (Model Context Protocol) server for Telegram. It links your own Telegram account to ChatGPT, Claude, Claude Code and other MCP clients and works as a transit: when your AI assistant asks, Postun passes it your chats, message search results or public channel posts, and keeps nothing itself. Messages exist only in memory while they are handed over; they are not stored, logged or viewed by Postun, and only read scopes exist, so nothing can be sent, edited or deleted. You decide which accounts and which scopes each AI client gets, and you can revoke access at any time. Files are implemented but not yet verified on production (see Beta status).

• Site: https://postun.org (English, Русский, Español, Português, Deutsch)

• Cabinet: https://app.postun.org

• MCP endpoint: https://mcp.postun.org/mcp

• Repository: https://github.com/AiReformator/postun

• Status: free beta, experimental. No independent security audit has been done.

What it is / Who it's for

Postun is a connector between a Telegram user account (not a bot) and an AI client that speaks MCP. After you link your account, the AI client can call a small set of read-only tools: list your dialogs, read message history, search messages, look at public channels and fetch file metadata or files.

It is for people who want an AI to help with their own Telegram data:

• summarize a group chat or a long conversation you missed;

• find something in your chat history by meaning, not only by keyword;

• review and analyze public channels you follow;

• pull context from Telegram into a ChatGPT, Claude or Claude Code session.

What it is not:

• Not a Telegram bot and not an "AI bot inside Telegram". Nothing is added to your chats and nothing talks in your name.

• Not a way to send messages, delete anything or change anything in Telegram. No write scope exists.

• Not zero-knowledge. See Security and privacy model.

Related MCP server: MCP Telegram Cloud

How it works

Telegram login ──> QR link ──> OAuth grant ──> MCP tools
(OIDC, cabinet)   (MTProto,    (you pick the    (read-only calls from
                   optional     accounts and     ChatGPT / Claude /
                   2FA password) read scopes)    Claude Code)

1. Sign in to the cabinet at https://app.postun.org with Telegram.

2. Link your account by scanning a QR code in the Telegram app (MTProto login). If you use a cloud password (2FA), you enter it in the cabinet during linking.

3. Connect an AI client. The client opens an OAuth flow (with PKCE) on Postun's authorization server. On the consent screen you choose which linked accounts and which scopes (accounts, dialogs, history and search, public channels, files) this client may use.

4. The AI client calls MCP tools at https://mcp.postun.org/mcp with its access token. Each call is checked against the grant, then Telegram is read and the result is returned to the client.

You can revoke a client's grant or unlink an account in the cabinet at any time.

Quick start (for users)

1. Open https://postun.org and go to the cabinet https://app.postun.org. Sign in with Telegram.

2. Link your Telegram account with the QR code.

3. Connect your AI client using the MCP URL:

https://mcp.postun.org/mcp

ChatGPT (custom connector, developer mode): in ChatGPT settings enable developer mode, add a custom MCP connector, paste the MCP URL above, and complete the OAuth consent screen. Menu names depend on your plan and ChatGPT version.

Claude Code:

claude mcp add --scope user --transport http postun https://mcp.postun.org/mcp

Then run /mcp inside Claude Code and authenticate postun. Note: the Claude Code flow has not yet been verified on production (see the status table).

Other MCP clients that support remote HTTP MCP servers with OAuth can use the same URL.

Tip for the beta: try it first with a test account or non-sensitive chats.

MCP tools

All tools are read-only. There is no tool that sends, edits or deletes anything, and no write scope. The server enforces the scope of every tool regardless of client hints.

Security and privacy model

• Encryption at rest. Telegram sessions are encrypted with AES-256-GCM. Each account has its own key, wrapped by a key-encryption key (KEK) that is stored as a Cloudflare secret.

• No logs of your conversations or requests. Cloudflare logs are disabled, and the code may log only constant strings. This is enforced in CI (npm run check:logging and checks on Cloudflare logging configuration).

• No archive. Message and file content exists only in memory while it is being delivered to your AI client. Postun stores encrypted Telegram sessions, grants (permissions), daily counters and limited service metadata.

• Read-only by construction. Only read scopes exist: accounts:read, dialogs:read, messages:read, channels:read, media:read.

• Revocable. Revoke a client or unlink an account in the cabinet whenever you want.

• Open source. The code that handles encryption, access checks and logging is public (see the next section).

What this is not. Postun is not zero-knowledge. The operator and the infrastructure (Cloudflare Workers and Durable Objects) are part of the trust model: while a request is served, the service has to decrypt your session to talk to Telegram, and a malicious or compromised operator who controls the deployment and its secrets could technically read your data. The AI provider you connect (OpenAI, Anthropic, etc.) receives what the tools return and keeps it according to its own rules. Please use a test account first and decide what you are comfortable sharing.

Details: docs/03_SECURITY_PRIVACY.md.

Philosophy: open by design (Kerckhoffs's principle)

The code is fully open so that anyone can check how encryption, access checks and the no-logs rule actually work. Following Kerckhoffs's principle, security must rely only on the secrecy of keys, not on hiding the system's design. Real keys live in Cloudflare secrets and never in this repository; what stays closed is only keys, tokens, user data, access configuration of our deployment, the operator's internal working material (including instructions to AI models) and material of closed security incidents. If you do not want to trust our deployment, read the code and run your own (see Self-hosting).

Beta status

Status comes from apps/web/status.json (updated 2026-11-05). Only features with a recorded acceptance run on production are marked verified. The same table is on the site at https://postun.org/#features; service uptime is at https://postun.org/status/.

"Not verified yet" means the code exists but has not passed an acceptance run on production. Do not rely on those features yet.

Free beta limit: 10,000 successful operations per UTC day per owner.

Telegram flood protection: Postun's main protection is obeying Telegram itself: when Telegram answers FLOOD_WAIT, the wait is stored and no call reaches Telegram until it ends, so the account is never hammered into longer penalties. On top of that there is only a generous spam guard (about 120 calls a minute and 5,000 an hour per account), channel search and global search are spaced to about one per second (short queue, not a refusal), and deep paging through dialogs or global search is bounded. Heavy normal work, such as reading dozens of channels with thousands of messages, is not slowed down. Your AI is told the rules and gets a limits object in every result. Telegram publishes no numeric limits, so these numbers are initial and tunable (see docs/02_ARCHITECTURE.md).

Self-hosting

Running Postun in your own Cloudflare account, with your own keys, is planned and described in docs/04_DEPLOYMENT.md and docs/DEPLOY_RUNBOOK.md. It is not yet a polished, supported install path. The goal is that the service does not depend on postun.org being up.

Development

Postun runs on Cloudflare Workers, Durable Objects (SQLite-backed), D1 and Workers KV, written in TypeScript. Node.js 26 (.nvmrc), npm workspaces, one lockfile.

source ~/.nvm/nvm.sh && nvm use   # Node 26
npm ci
npm run lint
npm run typecheck
npm test
npm run build
npm run check:secrets
npm run check:logging

npm run ci runs the whole chain. Tests use synthetic data and a local Workers runtime (Miniflare/workerd); real Telegram, OIDC identity provider and Cloudflare resources are not used in CI. Real secrets are set only with wrangler secret put in your own Cloudflare account; variable examples are in apps/*/.dev.vars.example and templates/.env.example.

Repository layout:

apps/web/            Cloudflare Workers static assets: beta landing, docs, cabinet (static)
apps/auth/           postun-auth: Telegram OIDC, web session, MCP OAuth (authorization server), cabinet API
apps/mcp/            postun-mcp: MCP resource server, SessionAndQuotaDO, Telegram (mtcute) adapter
apps/admin/          postun-admin: administrator OIDC BFF, aggregates, suspend/resume
packages/contracts/  shared schemas, scopes, envelope encryption, cursors, RPC contracts
migrations/control/  D1 postun-control (auth only)
migrations/admin/    D1 postun-admin-meta (admin only)

Guidelines for contributors: CONTRIBUTING.md. Use synthetic data in tests and issues; never attach real credentials, login codes, private chats or files.

Documentation

The in-depth documentation is written mostly in Russian.

Security reporting

Report vulnerabilities privately through GitHub private vulnerability reporting for this repository; see SECURITY.md. Do not put exploit details, Telegram sessions, private conversations, login codes or tokens into public issues.

License

Apache-2.0.

FAQ

What is a Telegram MCP server? MCP (Model Context Protocol) is an open standard that lets AI clients such as ChatGPT, Claude and Claude Code call external tools. A Telegram MCP server exposes Telegram data as such tools. Postun is a hosted, read-only one that works with your own Telegram account.

Is Postun a Telegram bot? No. A bot lives inside Telegram and you chat with it. Postun does not add anything to Telegram: it uses a login of your own user account and exposes read-only tools to your AI client. If you are looking for "ChatGPT bots in Telegram", this is a different thing.

How do I connect Telegram to ChatGPT or Claude? Sign in at https://app.postun.org, link your account by QR code, then add https://mcp.postun.org/mcp as a custom MCP connector in ChatGPT (developer mode), or run claude mcp add --scope user --transport http postun https://mcp.postun.org/mcp for Claude Code. See Quick start.

Is it safe? It is designed to be careful: read-only scopes, encrypted sessions, no logs of conversations, revocable access, open code. But it is a beta without an independent audit, and it is not zero-knowledge: the operator and Cloudflare infrastructure are part of the trust model, and your AI provider keeps data under its own rules. Try it with non-sensitive data first.

Is it free? Yes, the beta is free, with a limit of 10,000 successful operations per UTC day per owner. There are no payments in the beta, and the limit may change.

Can the AI send messages or change my Telegram? No. Only read tools exist, and the server enforces read scopes.