Fast MCP Telegram

Get messages in chat

get_messages

Read-onlyIdempotent

Retrieve or search messages in a Telegram chat: browse latest, find by text, fetch specific IDs, or load reply threads. Filter by sender, date, and include surrounding context or direct replies.

Instructions

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

Changed3 schema fields changedv0.45.0Sep 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_replies=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. 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).",
+  "type": "string"
+}

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"
+}

Changed3 schema fields changedv0.36.0Jun 18, 2026

removedOutput schema / additionalProperties
```
Removed value: -true
```

addedOutput schema / description

Added value: +"Return type for ``search_messages_globally`` and ``get_messages``."

addedOutput schema / properties

Added value: +{
+  "_warning": {
+    "type": "string"
+  },
+  "action": {
+    "type": "string"
+  },
+  "code": {
+    "type": "integer"
+  },
+  "error": {
+    "type": "string"
+  },
+  "error_code": {
+    "type": "string"
+  },
+  "exception": {
+    "additionalProperties": true,
+    "type": "object"
+  },
+  "has_more": {
+    "type": "boolean"
+  },
+  "messages": {
+    "items": {
+      "additionalProperties": true,
+      "type": "object"
+    },
+    "type": "array"
+  },
+  "ok": {
+    "type": "boolean"
+  },
+  "operation": {
+    "type": "string"
+  },
+  "params": {
+    "additionalProperties": true,
+    "type": "object"
+  },
+  "total_count": {
+    "type": "integer"
+  }
+}

First observedv0.21.0May 28, 2026

TDQS

A4.5/5.0

Behavior5/5

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses meaningful behavioral traits: include_replies 'costs one API call (not batchable),' context is 'Disabled when result count exceeds cost-based caps,' and the server-side per-chat filter for from_user. These details inform the agent about side effects and limitations without contradicting annotations.

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 compact yet information-dense, front-loading the core action in the first sentence and then detailing key usage points and constraints. It avoids fluff and ends with a documentation link, earning each sentence's place.

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 tool with 13 parameters, an output schema, and read-only annotations, the description provides a comprehensive overview: it lists all major modes, notes cost-related behavior, states success response fields, and links to full documentation. This is sufficient for an agent to select and invoke the tool correctly without needing to infer critical details.

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?

The schema descriptions already cover all 13 parameters with 100% coverage, including the mutual exclusivity of message_ids and the per-chat nature of from_user. The description's parameter-related guidance, such as 'Use context to include neighboring messages,' largely repeats what the schema already states, adding minimal semantic value beyond the structured fields.

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?

The description clearly states the tool reads or searches messages within one chat, enumerating four distinct modes: browse latest, search text, fetch by ids, and load replies. The phrase 'in one chat' explicitly distinguishes it from the sibling tool search_messages_globally, establishing scope and resource.

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 clear usage context, such as 'Use from_user to filter by sender (server-side, per-chat only)' and 'Do not combine message_ids with query or reply_to_id,' which set expectations for parameter combinations. However, it does not explicitly mention when to prefer the global search sibling or exclude this tool for cross-chat searches, so it stops short of full when-not guidance.

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

Deploy Server