Telegram MCP

Get messages in chat

get_messages

Read-onlyIdempotent

Read Telegram chat history: browse, search by text, fetch by message IDs, or load replies. Filter by date range and use @username as chat_id.

Instructions

Read chat history: the conversation, dialog, or DM with one person, group, or channel. Browse the latest messages, search text inside the chat, fetch by ids, or load replies to a message (comments, forum topics, threads). Accepts a @username directly as chat_id, so a known handle needs no lookup step. Filter a time window with min_date and max_date (e.g. what was written this morning). Do not combine message_ids with query or reply_to_id. Success: messages, has_more, optional total_count and discussion fields. Full documentation: https://github.com/leshchenko1979/fast-mcp-telegram/blob/main/docs/Tools-Reference.md

Input Schema

TableJSON Schema

Name	Required	Description	Default
`limit`	No	Maximum messages to return (recommended 50 or less).
`query`	No	Search within this chat only; comma-separated terms. Omit to browse latest or use message_ids / reply_to_id modes.
`chat_id`	Yes	Target chat: numeric id (e.g. -100…), a username with or without the leading @ (resolved server-side, no lookup call needed), or 'me' for Saved Messages.
`max_date`	No	Inclusive maximum date filter (ISO 8601 date or datetime). Omit for no upper bound.
`min_date`	No	Inclusive minimum date filter (ISO 8601 date or datetime). Omit for no lower bound.
`message_ids`	No	Exact message ids to fetch. Mutually exclusive with query and reply_to_id.
`reply_to_id`	No	Anchor message id: channel post id, forum topic_id from get_chat_info, or a message id for direct replies. Use with thread_scope.
`thread_scope`	No	Only with reply_to_id. auto: full forum topic (topic_id) or channel comment thread via getReplies; else direct replies. full: nested branch under a message id (forum in-topic uses search window, not whole topic); supergroup threads use search top_msg_id. direct: immediate replies only.	auto
`auto_expand_batches`	No	Extra search batches to run when filters narrow results. Higher values may return more matches at the cost of latency.
`include_total_count`	No	If true, response may include total_count where supported (per-chat search; ignored for global search).

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.34.0Sep 12, 2026

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, lowering the burden, but the description still adds real behavioral content: the mutual-exclusion constraint on input modes, the @username shortcut that avoids a lookup call, and the success shape (messages, has_more, total_count, discussion). Pagination semantics beyond the has_more flag are not elaborated.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and organized as scope, modes, shortcuts, constraints, and return shape. The synonym list ('conversation, dialog, or DM') and the trailing doc link add bulk, but nearly every sentence carries operational information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 10-parameter tool with an output schema, the description covers purpose, mode selection, the exclusivity constraint, the username shortcut, and the return shape, so an agent has everything needed to call it correctly. Return-value detail is a bonus rather than a necessity given the output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3, and the description genuinely adds over it: it explains the @username-as-chat_id shortcut, illustrates the date window with a use case ('what was written this morning'), and restates the message_ids/query/reply_to_id exclusivity that the schema only states per-parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Read chat history') and immediately enumerates the four distinct modes (browse latest, search text, fetch by ids, load replies), which separates it from the sibling search_messages_globally ('within this chat only'). An agent can identify the tool and its scope without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete mode-selection guidance ('Browse the latest messages, search text inside the chat, fetch by ids, or load replies') and an explicit exclusion rule ('Do not combine message_ids with query or reply_to_id'). It does not explicitly name search_messages_globally as the alternative for cross-chat search, so routing for the global case is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server