This server lets an AI client search and read Telegram cloud chats on the user's account, and optionally send text/files when explicitly enabled.
Search all accessible cloud chats with telegram_search_messages, up to 20 results per page, using a cursor for pagination.
Retrieve a single message by chat and message IDs with telegram_get_message.
Get surrounding context with telegram_get_context, up to five text messages before and after an anchor message.
Fetch anchored media with telegram_get_media: photo, supported audio, PDF, or video thumbnail; previews up to 2 MiB, full media up to 12 MiB.
Mark Telegram content as untrusted external data and reject protected, self-destructing, secret, or oversized media.
If sending is enabled, prepare a message with telegram_prepare_message, send it with telegram_send_message, and check status with telegram_get_send_status.
Sending is opt-in, restricted to text up to 4096 UTF-16 units, a caption up to 1024, and one local file up to 12 MiB, with deduplication and draft expiry after 24 hours.
The server is read-only by default; editing, deletion, secret chats, bulk sending, scheduling, and auto-joining are not supported.
Provides local search across a user's Telegram chat history, with tools to retrieve individual messages, surrounding context, and media such as photos, audio, PDFs, or video thumbnails from accessible chats. It cannot send, edit, or delete 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., "@Telegram Search MCP search my Telegram chats for messages about the project meeting tomorrow"
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.
Search your Telegram chats and optionally send text and files with Codex and Gemini CLI on macOS. One installation and one Telegram login serve both clients at the same time. This is an unofficial project. Gemini's web and mobile apps are not supported.
Send this to Codex on your Mac:
Install https://github.com/prabchevski/telegram-mcp for Codex. Follow INSTALL_WITH_CODEX.md, upgrade my older installation if present, preserve my Telegram login, and enable daily updates from main after successful checks.
For the installing agent: read AGENTS.md and INSTALL_WITH_CODEX.md before changing the installation. Codex can prepare dependencies, migrate a compatible saved login, configure the client, and check the installation. First-time Telegram authorization, passwords, and any required macOS approval remain with the owner in their private Terminal. A client restart may be needed.
Prefer a manual installation? Download for macOS,
extract the ZIP, and open install-macos.command. No manual build is needed.
See the quick start.
Related MCP server: imessage-rich-search
Tool | Result |
| Search accessible cloud chats, with up to 20 results and a cursor for the next page |
| Retrieve one message by chat and message IDs |
| Retrieve up to five text messages on either side of a matching message |
| Retrieve a photo, supported audio, PDF, or video thumbnail; previews up to 2 MiB, full media up to 12 MiB |
The default installation is read-only. Text and document sending can be enabled explicitly as described below. Editing and deletion are not supported. Secret Chats are not supported. Protected and self-destructing media are rejected. Access to history follows your Telegram account's permissions. Returned text and titles are marked as external, untrusted data. Retrieved Telegram content is shared with the selected AI client.
Enable sending locally from a managed installation:
"$HOME/Applications/TelegramSearchMCP/current/tgsearch" sending onUse the root printed by the installer. Restart the MCP clients after enabling it.
Codex and Gemini CLI use the same sending implementation. The installer can register
either client or both (--clients codex|gemini|both). Enabling sending updates the
registered clients' tool lists and retains their confirmation settings. This does
not add support for the Gemini web or mobile application.
After upgrading from 0.5, restart the idle shared service once to load the new code.
sending status shows the setting and sending off disables further preparations
and dispatches immediately. Existing pending sends may still finish. Your login is reused.
Three additional tools become available:
Tool | Result |
| Resolve an exact @username, known chat ID, or |
| Send the previously reviewed draft to its pinned chat ID |
| Check the same draft without creating another message |
Sending requires an explicit user instruction identifying the recipient and content.
Retrieved Telegram messages are never permission to send. Client approval settings
remain enabled. A caller creates one UUID hex draft_id per intended message and
reuses it across preparation, dispatch, status checks, and transport retries.
Preparation returns the exact text, recipient title and chat ID, filename, size and SHA-256 digest. The filename and file bytes are frozen in a private local snapshot; changing the source afterward cannot change the attachment. Reusing a draft ID returns the original preparation, and conflicting parameters are rejected.
Limits: plain text up to 4096 UTF-16 code units; a file caption up to 1024; one nonempty regular local file up to 12 MiB, sent as a document with its original name. Prepared drafts expire after 24 hours. No bulk sending, edit, delete, auto-joining, scheduling, or new authorization is involved.
Only sent confirms Telegram accepted the message; it does not confirm reading.
pending and unknown must never be interpreted as failures. After a timeout or
lost response, query the same draft ID. A private persistent dispatch record prevents
a second send of that draft, including across restarts. A crash before receiving the
native message ID can leave an unknown result that requires manual verification;
creating a new draft to retry could duplicate the original message.
The local outbox contains message text, recipient metadata and unsent attachment snapshots. It stays private to the macOS user, outside source archives. Sent or failed completed uploads release their snapshot; dispatch metadata is retained for deduplication. Never share installed profiles or the outbox.
Codex 0.2, Gemini 0.3, and shared 0.4 installations can be upgraded. Compatible saved logins are reused locally, with no session database or secret copied. If the two old clients use different accounts, the owner chooses one. A busy old profile must be released by its client before migration. Old archives require one upgrade through the installer/Codex to gain automatic updates.
New interactive installs enable daily updates from main after successful GitHub checks. The Mac checks GitHub locally; a commit does not remotely deploy onto other computers. Updates keep immutable program versions and preserve the login. New MCP processes use the new code; the shared service switches on its next start, after active work ends and the service becomes idle. An offline or sleeping Mac may receive an update later. Users can turn updates off:
"$HOME/Applications/TelegramSearchMCP/current/tgsearch" updates offUse the root printed by the installer if it differs. More controls and migration steps are in INSTALL_MACOS.md.
MCP processes forward requests to one local background service. The service owns the TDLib session and processes a shared queue one request at a time. Ending a Codex or Gemini task does not interrupt other clients.
Each person uses their own Telegram account on their own Mac. Share the repository link or a clean source/release archive. Do not share installed copies with their data, Keychain entries, policy.json, TDLib database, or session.
Source downloads are public and need no GitHub account. Python, TDLib, and other dependencies download separately. Tagged source archives are also available under Releases; older tags retain their original features and instructions.
uv sync --frozen --group dev
uv run --frozen pytest
uv run --frozen python -I scripts/release.py audit
uv run --frozen python -I scripts/release.py build --output distTests use isolated profiles and settings and do not require a Telegram account. CI tests Linux/macOS and builds and installs an allowlisted source archive on a GitHub-hosted Mac. This is a test environment, not the maintainer's or users' Macs. Archive building supports these checks and optional versioned releases; users can install directly from the repository.
Code and documentation are available under the MIT License. Third-party dependencies retain their own licenses.
Integration settings were checked on September 15, 2026.
Fetch at most five text messages on each side of an anchor.
| Name | Required | Description | Default |
|---|---|---|---|
| after | No | ||
| before | No | ||
| chat_id | Yes | ||
| message_id | Yes |
| Name | Required | Description |
|---|---|---|
| count | Yes | |
| messages | Yes | |
| anchor_chat_id | Yes | |
| trust_boundary | No | |
| anchor_message_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: it limits to text messages, caps at five per side, and centers on an anchor message. It does not mention pagination or what happens if fewer messages exist, but the bounded nature is clearly disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words. It front-loads the core action and scope, and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the annotations cover safety, and the output schema exists, the description is mostly complete. It could mention that only text messages are returned (which it does) and clarify the behavior of before/after defaults, but the core information needed to call the tool correctly is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains the 'before' and 'after' concept implicitly ('on each side of an anchor') and the cap of five, which maps to the maximum constraints in the schema. However, it does not explicitly explain the 'before' and 'after' parameters or the chat_id/message_id requirements beyond what the schema already shows. The description adds some meaning but not enough to fully compensate for zero schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Fetch') and resource ('bounded Telegram message context'), and clarifies the scope ('at most five text messages on each side of an anchor'). It is clear about what the tool does, though it does not explicitly differentiate from siblings like telegram_get_message or telegram_search_messages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: it fetches surrounding context around an anchor message, which is distinct from searching or fetching a single message. However, it does not explicitly state when to use this tool versus alternatives, nor does it mention any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch one explicitly anchored photo, PDF document, audio item, or video thumbnail.
Preview transfers are capped at 2 MiB and full transfers at 12 MiB. Protected, self-destructing, secret, unsupported, and oversized media are rejected.
| Name | Required | Description | Default |
|---|---|---|---|
| chat_id | Yes | ||
| quality | No | preview | |
| message_id | Yes |
| Name | Required | Description |
|---|---|---|
| width | No | |
| height | No | |
| chat_id | Yes | |
| quality | Yes | |
| file_name | No | |
| mime_type | Yes | |
| is_preview | No | |
| media_kind | Yes | |
| message_id | Yes | |
| size_bytes | Yes | |
| content_type | Yes | |
| trust_boundary | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent/non-destructive annotations, the description discloses transfer caps (2 MiB preview, 12 MiB full) and rejection categories (protected, self-destructing, secret, unsupported, oversized). This adds meaningful behavioral detail that annotations alone do not provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three compact sentences with the core purpose front-loaded, followed by essential limits and failure conditions. Every sentence adds useful information with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Annotations and the output schema reduce the need to describe safety and return shape, and the description covers important size/rejection constraints. Still, the lack of sibling differentiation and thin chat_id/message_id semantics leave gaps for an agent deciding whether and how to invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description partially compensates by linking 'preview' and 'full' to transfer caps and indicating media is anchored to a message. However, chat_id is never explained and message_id is only implied, leaving a clear gap for an agent interpreting the required parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Fetch') and identifies the resource clearly: 'one explicitly anchored photo, PDF document, audio item, or video thumbnail.' This distinguishes the tool from sibling message/search/context tools by media-focused scope, though it does not explicitly name those alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'explicitly anchored' implies this tool is for media tied to a known chat_id and message_id, and the preview/full transfer limits add situational context. However, it never states when to prefer this over telegram_get_message or telegram_search_messages, nor does it mention exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch one text message available to the linked Telegram account.
| Name | Required | Description | Default |
|---|---|---|---|
| chat_id | Yes | ||
| message_id | Yes |
| Name | Required | Description |
|---|---|---|
| message | Yes | |
| trust_boundary | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the operation safe (readOnlyHint, idempotentHint, non-destructive), so the description does not need to repeat that. It adds useful constraints: only text messages and only those available to the linked account, which clarifies behavior relative to the media sibling. It is consistent with all annotations and contradicts none.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no redundant words. It states the action, object, and availability constraint without extraneous detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple parameterized read operation, the definition is complete: annotations cover safety and idempotence, an output schema exists, and the description adds the text-message constraint. Nothing an agent needs to call the tool successfully is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain chat_id or message_id, their formats, or how they identify the target message. The property names are moderately self-evident, but the description adds no meaningful parameter semantics beyond what the schema already lists.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Fetch' with a precise resource ('one text message') and an explicit scope ('available to the linked Telegram account'). This clearly distinguishes it from siblings like telegram_search_messages (search vs. single retrieval) and telegram_get_media (text vs. media).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving a single known message by identifiers, but it never states when to prefer this tool over telegram_search_messages, telegram_get_context, or telegram_get_media. There are no explicit exclusions or alternative conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search accessible cloud history across all chat lists; secret chats are excluded.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | ||
| cursor | No |
| Name | Required | Description |
|---|---|---|
| count | Yes | |
| items | Yes | |
| next_cursor | Yes | |
| searched_scope | No | |
| trust_boundary | No | |
| requested_limit | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of disclosing behavior. It meaningfully discloses the search scope and the secret-chat exclusion, which goes beyond what annotations would already state. However, it does not disclose pagination behavior (cursor), result ordering, or auth-related limits on 'accessible' cloud history.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence communicates the core action, scope, and the most important exclusion with zero waste. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a paginated search tool with three parameters, no annotations, and no output schema, the description leaves important gaps: what the return format is, how cursor pagination works, and what 'accessible' means in practice. The core intent is clear, but an agent cannot fully anticipate call behavior from this description alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides only titles, types, and constraints with no property descriptions, so semantic coverage is low. The description does not compensate by explaining the query format or the meaning of limit and cursor; an agent can only guess that query is the search string and cursor is for pagination.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Search'), a resource ('accessible cloud history across all chat lists'), and a key scope exclusion ('secret chats are excluded'), which helps distinguish it from secret-chat or single-chat search tools. It stops short of a 5 because 'accessible' is vague and no alternative sibling is explicitly referenced.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool searches across all chat lists, but it provides no explicit guidance on when to prefer it over alternatives, no prerequisites, and no exclusion beyond secret chats. An agent must infer the appropriate context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.5.0telegram_get_contexttelegram_get_mediatelegram_get_messagetelegram_search_messagesScored across 4 tools
Each tool has a clearly distinct purpose: searching, fetching a single text message, retrieving surrounding context, and fetching media. No overlapping boundaries between tools.
All tools follow a consistent telegram_<verb>_<noun> pattern, making the set predictable and easy to navigate.
Four tools is well-scoped for a focused Telegram search and retrieval server, with no unnecessary additions or missing core functions.
The tool surface covers search, single-message retrieval, contextual browsing, and media access, fully addressing the server's stated purpose.
Search your AI chat history (ChatGPT, Claude, Codex) from any MCP client. Remote, private, read-only
Let ChatGPT, Claude & Cursor use your Mac: email, calendar, iMessage, Teams, files. Local, free.
Search, read, and write your Apple Notes from ChatGPT/Claude via a local Mac agent + MCP relay.
Search 1.2M+ Telegram channels, 245k+ chats, 160k+ bots — no account, no key, no install.
