Fast MCP Telegram

Get messages in chat

get_messages

Read-onlyIdempotent

Read or search messages in one Telegram chat: browse recent history, search text, fetch specific IDs, or load replies and threads. Filter by sender and date to find conversations.

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

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "chat_id": "<chat_id>"
    },
    "name": "get_messages"
  }
}

Input 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

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

Behavior4/5

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real behavioral detail beyond them: ascending date ordering in every mode, limit selecting the newest N, context being silently disabled when cost caps are exceeded, and include_replies costing one non-batchable API call per result. These are non-obvious traits an agent would otherwise get wrong.

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 purpose and mode list, then one clause per parameter concern, then ordering and return shape. It is dense but every sentence carries an operational fact; the compression does make some clauses hard to parse on first read (e.g. the thread_scope discussion is left to the schema).

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 13-parameter tool this is thorough: required chat_id handling, all mode combinations, ordering guarantees, cost caveats, and the success shape (messages, has_more, optional total_count and discussion fields) are all covered. With an output schema present, the description correctly stops at naming the top-level fields rather than re-documenting them.

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 coverage is 100%, so the baseline is 3, but the description adds cross-parameter semantics the schema cannot express: message_ids being mutually exclusive with query and reply_to_id, from_user being a server-side per-chat filter, and context requiring chat_id. It also clarifies that limit picks the newest N while output is ordered oldest-first, which resolves an ambiguity the schema leaves open.

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?

Opens with a specific verb and resource ("Read or search messages in one chat") and immediately enumerates the four modes: browse latest, search text, fetch by ids, load replies. The "in one chat" scope distinguishes it from the sibling search_messages_globally without the agent needing to open either 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 mode-selection context (from_user for sender filtering, context for neighboring messages, include_replies for replies) and an explicit exclusion: "Do not combine message_ids with query or reply_to_id." It never names a sibling tool as an alternative, so it stops short of full routing guidance, but the conditions for each mode are clear.

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

Deploy Server