Fast MCP Telegram

by ru.l1979.tg-mcp

Get messages in chat

get_messages

Read-onlyIdempotent

Read or search messages in one chat: browse latest, search text, fetch by ids, or load replies to a message (comments, forum topics, threads). Use from_user to filter by sender (server-side, per-chat only). Use context to include neighboring messages and reply chains around each result. Use include_replies to fetch up to 5 direct replies per result. 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/alexeyleshchenko/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…), username without @, or 'me' for Saved Messages.
`context`	No	Number of surrounding messages to include as context for each search result. 0 = disabled (default). 1-10 = include N messages before and N after each result. Also fetches the message being replied to and top replies (if include_replies=true). Requires chat_id. Disabled when result count exceeds cost-based caps.
`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.
`from_user`	No	Only return messages from this sender. Not a display-name or contact-name search — bare strings resolve like chat_id via get_entity (usernames are case-insensitive and may match an unrelated channel). Prefer @username, phone (+…), or numeric user id. Also accepts 'me', 'self', t.me URL, -100 prefixed id. Uses Telegram's native from_id server-side filter (per-chat search only).
`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
`include_replies`	No	If true, fetch up to 5 direct replies per search result and attach as replies. Each result costs one API call (not batchable). Default: false.
`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
`ok`	No
`code`	No
`error`	No
`action`	No
`params`	No
`_warning`	No
`has_more`	No
`messages`	No
`exception`	No
`operation`	No
`error_code`	No
`total_count`	No

Schema Changelog

Changes observed during successful MCP inspections. Dates show when Glama detected each change.

Changed1 schema field changedJul 12, 2026

changedInput schema / properties / from_user / description

Previous value: -"Only return messages from this sender. Accepts: numeric user id, @username, phone (+…), 'me', 'self', t.me URL, -100 prefixed id. Resolved via get_entity_by_id (same as chat_id). Uses Telegram's native from_id server-side filter (per-chat search only)."New value: +"Only return messages from this sender. Not a display-name or contact-name search — bare strings resolve like chat_id via get_entity (usernames are case-insensitive and may match an unrelated channel). Prefer @username, phone (+…), or numeric user id. Also accepts 'me', 'self', t.me URL, -100 prefixed id. Uses Telegram's native from_id server-side filter (per-chat search only)."

Changed3 schema fields changedJul 9, 2026

changedInput schema / properties / context / description

Previous value: -"Number of surrounding messages to include as context for each search result. 0 = disabled (default). 1–10 = include N messages before and N after each result. Also fetches the message being replied to and top replies (if include_reply_threads=true). Requires chat_id. Disabled when result count exceeds cost-based caps."New value: +"Number of surrounding messages to include as context for each search result. 0 = disabled (default). 1-10 = include N messages before and N after each result. Also fetches the message being replied to and top replies (if include_replies=true). Requires chat_id. Disabled when result count exceeds cost-based caps."

addedInput schema / properties / include_replies

Added value: +{
+  "default": false,
+  "description": "If true, fetch up to 5 direct replies per search result and attach as replies. Each result costs one API call (not batchable). Default: false.",
+  "type": "boolean"
+}

removedInput schema / properties / include_reply_threads

Removed value: -{
-  "default": false,
-  "description": "If true, fetch up to 5 direct replies per search result and attach as reply_thread. Each result costs one API call (not batchable). Default: false.",
-  "type": "boolean"
-}

Changed3 schema fields changedJun 26, 2026

addedInput schema / properties / context

Added value: +{
+  "default": 0,
+  "description": "Number of surrounding messages to include as context for each search result. 0 = disabled (default). 1–10 = include N messages before and N after each result. Also fetches the message being replied to and top replies (if include_reply_threads=true). Requires chat_id. Disabled when result count exceeds cost-based caps.",
+  "maximum": 10,
+  "minimum": 0,
+  "type": "integer"
+}

addedInput schema / properties / from_user

Added value: +{
+  "default": null,
+  "description": "Only return messages from this sender. Accepts: numeric user id, @username, phone (+…), 'me', 'self', t.me URL, -100 prefixed id. Resolved via get_entity_by_id (same as chat_id). Uses Telegram's native from_id server-side filter (per-chat search only).",
+  "type": "string"
+}

addedInput schema / properties / include_reply_threads

Added value: +{
+  "default": false,
+  "description": "If true, fetch up to 5 direct replies per search result and attach as reply_thread. Each result costs one API call (not batchable). Default: false.",
+  "type": "boolean"
+}

First observedJun 18, 2026

TDQS

A4.5/5.0

Behavior4/5

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the description doesn't need to restate safety. It adds valuable details like 'include_replies to fetch up to 5 direct replies', the mutual exclusion constraint, and the success field list ('messages, has_more, optional total_count and discussion fields'). It also points to full documentation, enhancing transparency. This goes well beyond the annotations without contradicting them.

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

Conciseness5/5

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

The description is a tightly packed paragraph of about 120 words. It front-loads the core purpose, then gives parameter guidance in order of relevance, ends with success fields and a docs link. Every sentence conveys actionable info—no filler, no redundancy. The structure flows logically from 'what it does' to 'how to use it' to 'what to expect'.

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?

Given the tool has 13 parameters, an output schema, and multiple modes (browse, search, fetch by ids, replies), the description covers the essential usage scenarios and constraints. It mentions the success response shape and links to full docs for edge cases. The presence of a rich output schema means the description doesn't need to repeat field details, yet it still summarizes what the caller should expect. This is complete for a tool of this complexity.

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?

The schema has 100% coverage with detailed per-parameter descriptions, so the baseline is 3. The description elevates this by explaining how parameters work together (e.g., 'Use context to include neighboring messages and reply chains around each result', 'Use include_replies to fetch up to 5 direct replies per result'), and clarifies positional semantics like 'Use reply_to_id with thread_scope' (implicitly). It also states the per-chat limitation of from_user. This adds integrative meaning beyond the schema.

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?

Description opens with 'Read or search messages in one chat' followed by explicit modes: 'browse latest, search text, fetch by ids, or load replies to a message'. This clearly distinguishes it from siblings like search_messages_globally by scoping to a single chat. The verb 'Read or search' is specific and the resource ('messages in one chat') is unambiguous.

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?

The description provides concrete usage guidance for several parameters ('Use from_user to filter by sender', 'Use context to include neighboring messages', 'Use include_replies to fetch up to 5 direct replies') and warns against invalid combos ('Do not combine message_ids with query or reply_to_id'). It stops short of explicitly naming alternative tools, though the 'in one chat' scope implicitly contrasts with global search. This is strong guidance but lacks a direct 'when not to use' statement.

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

All Fast MCP Telegram tools Inspect

Try in Browser

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?