fast-mcp-telegram

by io.github.leshchenko1979

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. Results are ordered by ascending date-time (oldest first) in every mode, including message_ids and nested context lists; limit selects the newest N. 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…), 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.

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.4/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=true, so the safety/profile is covered. The description adds valuable behavioral detail beyond these: result ordering (ascending date-time in every mode), that limit selects the newest N, and side-effect notes like 'Each result costs one API call' for include_replies. It doesn't cover rate limits or caps for context mode beyond a brief mention, so a 4 is appropriate.

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 front-loaded with the core action, then proceeds through modes, filters, constraints, and return shape in a logical order. Every sentence earns its place; there is no repetition or filler. The documentation URL is appended without disrupting the flow.

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

Completeness4/5

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

Given 13 parameters, a rich schema, and an output schema (which explains return values), the description provides a complete orientation: modes, ordering, mutual exclusions, and success fields. It could mention pagination behavior (has_more when limit is hit) or cost caps for context mode, but it is largely sufficient for correct invocation.

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

Parameters3/5

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

Schema coverage is 100%, so the baseline is 3. The description adds some meaning by explaining that from_user is a server-side per-chat filter and that context includes reply chains, but most parameter semantics (date filters, thread_scope enum, auto_expand_batches) are already fully documented in the schema. The description doesn't add significantly beyond what the schema provides.

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+resource ('Read or search messages in one chat') and enumerates the distinct modes (browse, search text, fetch by ids, load replies). The description clearly distinguishes it from search_messages_globally by emphasizing 'one chat' and from edit/send siblings. An agent can immediately tell what this tool is for.

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

Usage Guidelines5/5

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

Provides explicit when-to-use guidance for each mode (search text, fetch by ids, load replies) and states a critical mutual-exclusion rule ('Do not combine message_ids with query or reply_to_id'). It also names the alternative sibling (search_messages_globally) by contrast in the one-chat scope. This exceeds a typical usage guideline.

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

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.