Usage¶
Every resource and tool below reads your Telegram Archive viewer through its HTTP API, signed in once: the server keeps the session cookie and logs in again only when the viewer answers 401, so many calls cost one login against the viewer's limit of 15 logins per client IP in 5 minutes. Only refresh_stats asks the viewer to do something: it recalculates the archive's statistics. None of them changes a message, and none of them talks to Telegram.
Resources¶
| URI | What it returns |
|---|---|
telegram-archive://stats |
Chat count, message count, media count and total size of the archive |
telegram-archive://chats |
The 500 most recent chats with basic info (list_chats pages further) |
telegram-archive://folders |
Your Telegram chat folders |
telegram-archive://health |
Whether the viewer is up |
Tools¶
Most tools take a chat_id. Call list_chats first: the ref of each chat is its chat_id.
| Tool | What it does | Arguments |
|---|---|---|
list_chats |
Lists archived chats, most recent first. Each row has ref (the chat_id the other tools take), id (the numeric Telegram chat id), type, accounts (the archive accounts holding it) and its title or name |
limit (1 to 500, default 100), offset, search (part of a chat's name or username), archived (true or false), folder_id (from list_folders) |
list_folders |
Lists your Telegram chat folders and their ids | none |
search_all_chats |
Finds messages that contain words in every chat the login may see, newest first; each hit names its chat by ref. Needs a viewer with cross-chat search |
query, limit (1 to 100, default 20), offset (0 to 5000) |
search_messages |
Finds messages in one chat that contain a keyword | chat_id, query, limit (1 to 200, default 20), topic_id |
get_messages |
Returns a chat's messages, newest first | chat_id, limit (1 to 500, default 50), then either offset (up to 100000), or the keyset cursor before_date plus before_id, or after_id; topic_id |
get_message_context |
Returns one message with the messages around it, oldest first | chat_id, message_id, before and after (0 to 50 each, default 5) |
get_messages_by_date |
Returns every message of one calendar day, oldest first | chat_id, date (YYYY-MM-DD), timezone (IANA name, default UTC), limit (1 to 5000, default 1000), topic_id |
get_pinned_messages |
Returns a chat's pinned messages | chat_id |
get_topics |
Lists the forum topics of a chat, with the ids topic_id takes |
chat_id |
get_chat_stats |
Returns message and media counts, size and first and last message dates for one chat | chat_id |
get_media |
Returns the photo or file attached to one message: an image to look at, or the file's name, type and size | chat_id, message_id |
refresh_stats |
Makes the viewer recalculate the archive's statistics. Needs the viewer's master login; hidden with READ_ONLY=1 |
none |
Arguments are checked against each tool's schema before it runs: an unknown argument, a fraction where a whole number is due, or a value out of range comes back as an error the model can correct. Every tool answers with structuredContent matching its outputSchema, and the same data as JSON text for clients that read only text. A list the viewer returns as a bare array (messages, pinned messages) is wrapped as {"messages": [...]} in structuredContent.
Errors from the viewer come back as one fixed sentence per HTTP status (for example telegram-archive error 404: not found; check chat_id ...), never the viewer's own error text.
Forum topics¶
In a forum supergroup, get_topics lists the threads. Pass a topic's id as topic_id to get_messages, search_messages or get_messages_by_date to read only that thread; 1 is the General topic.
Around one message¶
After a search hit, or to see what a reply_to_msg_id points at, get_message_context returns that message with up to before older and after newer messages, oldest first, plus how many of each it found.
Paging through a long chat¶
get_messages pages two ways. offset skips that many messages, which gets slower the deeper you go. The keyset cursor does not: pass the date and id of the last message you received as before_date and before_id, and the next call returns the messages older than it. after_id returns the messages newer than an id. Dates are ISO 8601; a date without a timezone is UTC, which is how the archive stores them.
Looking at a photo¶
Every message row from get_messages, get_messages_by_date and search_messages carries reply_to_msg_id, the id of the message it answers, and media when it has a file or other media: media.type is the kind (photo, document, video, geo...) and media.url is set when the archive holds a file get_media can fetch. So from a reply such as "did you see my picture?" an agent reads reply_to_msg_id and passes it to get_media.
get_media takes the chat_id and the id of a message. Its first content block is always a JSON text block:
{"message_id": 42, "date": "2026-06-10T18:04:17", "sender": "Ada Lovelace", "text": "our new kitchen", "reply_to_msg_id": null, "media_key": "42_photo", "kind": "photo", "file_name": "1234567890_photo.jpg", "mime_type": "image/jpeg", "size_bytes": 412345, "image_returned": true, "width": 1568, "height": 1176, "scaled": true}
date, sender, text (the caption) and reply_to_msg_id describe the message. file_name, mime_type and size_bytes describe the original file; width, height and scaled describe the image sent.
- A JPEG, PNG, WebP or GIF follows as an MCP
imageblock, so the model sees it. When it is at most 1568 pixels on its longest side and at most 2,000,000 bytes it is sent as is. Otherwise it is sent as a JPEG scaled to 1568 pixels on its longest side, withscaled: true; the Claude API scales larger images down to that size anyway. Transparent areas turn white, and a JPEG stored sideways with an EXIF orientation tag is turned upright (and so always re-encoded). The type comes from the file's bytes, not from the archive's metadata. - Any other file gets the text block only, with
image_returned: falseand anotesaying why. So does an image whose file is over 20 MB or whose header claims more than 25 million pixels. The file itself is never sent, and an image is never cut short. - The location map picture the archive keeps for a
geoorvenuemessage comes back as an image too. - The call fails (
isError) with a sentence saying why when the message does not exist in that chat, has no media, has a kind with no file (a contact, a poll, a location without a map), has a file the archive has not downloaded, or when the viewer login has downloads turned off.
One day at a time¶
get_messages_by_date takes the day in the timezone you name, so 2026-06-10 in Europe/Madrid starts at 22:00 UTC the evening before. When the day holds more messages than limit, the newest are dropped and the result says truncated: true.
On the wire¶
Over HTTP the server has one JSON-RPC endpoint, /mcp; over stdio the same messages go through the process's standard input and output. It speaks MCP 2026-07-28 and every earlier revision down to 2024-11-05:
- A client on 2025-11-25 or earlier calls
initialize, thenresources/listandresources/read,tools/listandtools/call. - A 2026-07-28 client skips the handshake: it calls
server/discoverand sends its protocol version in each request's_meta. Tool and resource lists then carry cache hints (ttlMs300000,cacheScopepublic); resource reads areprivatewith no caching.
Any MCP client does this for you; MCP Inspector shows each call if you want to watch.