Provides tools for interacting with a personal Telegram account, including reading chats and history, searching messages, sending and replying to messages, uploading and downloading files, inspecting inline keyboards and pressing callback buttons, adding reactions, and editing or deleting the user's own messages.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@codex-telegram Check my unread messages from the family chat and summarize them"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
codex-telegram is a local Model Context Protocol server and Codex plugin for a personal Telegram account. It uses TDLib/MTProto, not the Bot API or browser automation.
The server runs on your computer. Telegram API credentials, TDLib database, authorization session, and downloaded media are stored in a private per-user directory and are never sent to a third-party service by this project.
Status: early release. Use a separate Telegram account for development and test any write workflow with Saved Messages first.
Read account details, chats, unread counts, and paginated chat history.
Diagnose local configuration, TDLib session, and authentication problems without exposing secrets.
Resolve a chat by name or @username, identify exact matches, and read its pinned message.
Search chats and messages, including contacts and public usernames.
Find documents, media, voice notes, and links in a specific chat without downloading them.
Send and reply to messages, upload files, and download selected media.
Inspect bot inline keyboards and press safe callback buttons.
Add or remove an explicitly approved emoji reaction.
Edit or delete only messages sent by the authenticated account, with explicit confirmation.
Keep all secret material and TDLib state outside the repository by default.
The server deliberately does not click URL, login, web-app, game, payment, or password buttons. It does not scrape Telegram Web or ask third-party bots for account/contact IDs.
Related MCP server: telegram-mcp
Node.js 20 or later.
pnpm 9 or later (corepack enable enables the version bundled with Node.js).
A Telegram api_id and api_hash from my.telegram.org.
Codex Desktop, if you want to use the plugin UI.
git clone https://github.com/aagafon1215-source/codex-telegram.git
cd codex-telegram
corepack enable
pnpm install --frozen-lockfile
pnpm run check
pnpm run setup
pnpm run loginpnpm run setup asks for the Telegram API ID and hash and stores them in a user-owned configuration file. It never writes credentials into the clone. pnpm run login asks for your phone number, Telegram code, and, if applicable, two-factor password.
On Windows, state is stored in %LOCALAPPDATA%\codex-telegram. On macOS/Linux it is stored in ~/.local/state/codex-telegram. Set TG_CONFIG_DIR before running setup to use another directory. You can also set TG_CONFIG_FILE, TG_DATABASE_DIR, TG_FILES_DIR, or TG_DOWNLOADS_DIR to absolute paths. Explicit downloads accept a file name only, are saved under TG_DOWNLOADS_DIR, and never overwrite a file. Downloads are capped at 100 MiB by default; set TG_MAX_DOWNLOAD_BYTES to a positive byte value to change the cap.
For local development only, copying .env.example to .env is supported. Set TG_USE_DOTENV=1 to opt in to loading it; this prevents a cloned repository from silently becoming the location of a Telegram session. Never commit that file.
If you used an older checkout that stored API credentials in .env, run pnpm run migrate-legacy-config once. It copies only the API credentials to the private configuration file and never overwrites an existing one; then run pnpm run login to create a session in the private state directory.
The repository is a local plugin source. After installing dependencies and building it, add the clone through your Codex local marketplace/plugin workflow. The MCP manifest uses portable settings:
{ "command": "node", "args": ["dist/index.js"], "cwd": "." }Codex starts the server itself; do not run pnpm start at the same time. TDLib permits only one process to use a session database. Start a new Codex task after installing or updating the plugin.
If node or pnpm is unavailable because you only have Codex Desktop installed, scripts/run-with-codex-runtime.ps1 is a Windows-only convenience launcher:
.\scripts\run-with-codex-runtime.ps1 setup
.\scripts\run-with-codex-runtime.ps1 login
.\scripts\run-with-codex-runtime.ps1 buildRead tools are read-only. telegram_send_message, telegram_reply_message, and telegram_send_file change external state; the included Codex skill requires an explicit recipient and exact content confirmation before they are called.
telegram_click_inline_button can trigger bot state changes. It may be used only after the user has explicitly authorized the requested button workflow. The tool accepts only callback buttons and refuses high-risk button types.
telegram_edit_own_message and telegram_delete_own_message can act only on outgoing messages from the authenticated account. Both require confirmation; deletion is marked destructive and asks Telegram to revoke the message for everyone when Telegram permits.
If Telegram is unavailable, begin with telegram_health. It reports only safe local status, the effective local TDLib paths, and a remediation hint; it never returns API credentials, login codes, or message content. A locked session is detected after a bounded 15-second connection attempt.
The plugin returns only the data requested by a tool. Avoid asking it to paste large private histories into a task, and do not paste Telegram login codes or API credentials into chat.
pnpm run typecheck
pnpm run test
pnpm run build
pnpm run checkRun the server manually only for MCP-client development:
pnpm startLogs are written to stderr so stdout remains valid MCP JSON-RPC.
Run pnpm install --frozen-lockfile && pnpm run check.
Run pnpm run plugin:validate.
Verify git status --ignored contains no credentials, TDLib database, downloaded files, or dist/ output.
Review SECURITY.md and docs/PRIVACY.md.
Create a version tag only after testing login and a read-only tool with a test account.
Please read CONTRIBUTING.md. For vulnerabilities, follow SECURITY.md instead of opening an issue with sensitive details.
Press a Telegram bot inline callback button by row and column. This sends a callback query and may change bot state. Callback buttons only; payments, URL/login, web-app, game, and password buttons are blocked.
Inputs: row (required), column (required), chat_id (required), message_id (required).
Delete one message previously sent by the authenticated Telegram account, revoking it for everyone when Telegram permits. This is destructive and requires explicit confirmation.
Inputs: chat_id (required), message_id (required).
Download media attached to one Telegram message. destination, when supplied, must be a new file name only; it is saved inside the configured Telegram downloads directory and never overwrites an existing file.
Inputs: chat_id (required), message_id (required), destination.
Edit one text message previously sent by the authenticated Telegram account. This changes external state: require explicit confirmation of the chat, message, and replacement text.
Inputs: text (required), chat_id (required), message_id (required).
Get details for one Telegram chat by its exact chat_id. For a private chat, returns the other person's Telegram user_id and profile fields when Telegram makes them available.
Inputs: chat_id (required).
List the inline buttons attached to one Telegram message. Use row and column values from this result with telegram_click_inline_button.
Inputs: chat_id (required), message_id (required).
Get the authenticated personal Telegram account. The phone number is intentionally omitted for privacy.
Inputs: no named parameters.
Read up to 100 messages in a known Telegram chat. The tool keeps requesting TDLib history internally when TDLib returns a partial page. Returns text and metadata only; media is not downloaded automatically.
Inputs: chat_id (required), limit, from_message_id.
Read the currently pinned message in a known Telegram chat. Returns text and metadata only.
Inputs: chat_id (required).
List recent Telegram chats that have unread messages.
Inputs: limit.
Diagnose local Telegram plugin setup without exposing credentials or message data. Optionally verifies the saved TDLib session.
Inputs: check_connection.
List recent Telegram chats, groups, channels, and Saved Messages. Use search when the user names a person or a chat.
Inputs: limit.
Add or remove your emoji reaction on one Telegram message. This changes external state: use only after the user explicitly confirms the chat, message, emoji, and whether it should be added or removed.
Inputs: emoji (required), chat_id (required), message_id (required), remove.
Reply to a specific Telegram message. This changes external state: call only after user confirmation of recipient and text.
Inputs: text (required), chat_id (required), reply_to_message_id (required).
Resolve a person, group, channel, or @username into candidate chat IDs for later read tools. This never sends a message.
Inputs: query (required), limit.
Find people, groups, channels, or Saved Messages by name, username, or title. Private-chat results include the contact's Telegram user_id where available. Before sending to an ambiguous name, search and confirm the intended chat.
Inputs: query (required), limit.
Find recent photos, videos, documents, audio, voice notes, animations, or URL messages inside one known chat. Returns message metadata only; no media is downloaded automatically.
Inputs: kind (required), chat_id (required), limit, query.
Search Telegram message text globally, or inside a supplied chat_id. Use this to locate a topic, deadline, specification, or file discussion.
Inputs: query (required), limit, chat_id.
Send a local file through the personal Telegram account. This changes external state: call only after the user explicitly confirms recipient, file, and caption.
Inputs: chat_id (required), file_path (required), caption.
Send text through the personal Telegram account. This changes external state: call only after the user has explicitly confirmed both recipient chat and exact message.
Inputs: text (required), chat_id (required).
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 20 tools
Most tools target distinct actions, but several discovery tools overlap: telegram_search_chats and telegram_resolve_chat both find chats by name and return candidate IDs, and telegram_list_chats vs telegram_get_unread both list recent chats. Descriptions are clear enough for an attentive agent, but boundary confusion is likely.
All tools share a telegram_ prefix and nearly all follow verb_noun naming like list_chats, send_message, and download_file. Minor deviations such as telegram_health, telegram_get_me, and telegram_get_unread break the pattern slightly but do not create serious confusion.
Twenty tools is on the heavy side, especially with several discovery tools that could plausibly be merged without losing capability. Each tool does represent a legitimate Telegram operation, so the count is defensible but feels somewhat bloated.
The server covers chat discovery, reading and searching messages, sending/reply, editing/deleting own messages, reactions, inline buttons, and media download. Missing capabilities like marking chats read, forwarding messages, or sending non-file media are minor gaps for a personal-assistant workflow and can be worked around.
Telegram bridge for your MCP-compatible agent. Bidirectional, no LLM in our stack.
Hosted Telegram MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Unofficial Telegram MCP server — read, search, reply and react in your own Telegram account.
Governed personal world model and memory for your AI agent. Pair once, connect over MCP.
