ListMessages
Retrieve messages from Telegram chats, channels, or dialogs in reverse chronological order. Filter unread messages or set a limit to display a specific number of latest messages.
Instructions
List messages in a given dialog, chat or channel. The messages are listed in order from newest to oldest.
If `unread` is set to `True`, only unread messages will be listed. Once a message is read, it will not be
listed again.
If `limit` is set, only the last `limit` messages will be listed. If `unread` is set, the limit will be
the minimum between the unread messages and the limit.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| dialog_id | Yes | ||
| limit | No | ||
| unread | No |
Implementation Reference
- src/mcp_telegram/tools.py:120-157 (handler)The main handler function for the ListMessages tool. It uses a TelegramClient to fetch messages from the specified dialog_id, optionally filtering by unread status and limiting the number. Returns text contents of messages.@tool_runner.register async def list_messages( args: ListMessages, ) -> t.Sequence[TextContent | ImageContent | EmbeddedResource]: client: TelegramClient logger.info("method[ListMessages] args[%s]", args) response: list[TextContent] = [] async with create_client() as client: result = await client(functions.messages.GetPeerDialogsRequest(peers=[args.dialog_id])) if not result: raise ValueError(f"Channel not found: {args.dialog_id}") if not isinstance(result, types.messages.PeerDialogs): raise TypeError(f"Unexpected result: {type(result)}") for dialog in result.dialogs: logger.debug("dialog: %s", dialog) for message in result.messages: logger.debug("message: %s", message) iter_messages_args: dict[str, t.Any] = { "entity": args.dialog_id, "reverse": False, } if args.unread: iter_messages_args["limit"] = min(dialog.unread_count, args.limit) else: iter_messages_args["limit"] = args.limit logger.debug("iter_messages_args: %s", iter_messages_args) async for message in client.iter_messages(**iter_messages_args): logger.debug("message: %s", type(message)) if isinstance(message, custom.Message) and message.text: logger.debug("message: %s", message.text) response.append(TextContent(type="text", text=message.text)) return response
- src/mcp_telegram/tools.py:104-118 (schema)Pydantic model defining the input arguments for the ListMessages tool: dialog_id (required int), unread (bool default False), limit (int default 100). Docstring provides the tool description.class ListMessages(ToolArgs): """ List messages in a given dialog, chat or channel. The messages are listed in order from newest to oldest. If `unread` is set to `True`, only unread messages will be listed. Once a message is read, it will not be listed again. If `limit` is set, only the last `limit` messages will be listed. If `unread` is set, the limit will be the minimum between the unread messages and the limit. """ dialog_id: int unread: bool = False limit: int = 100
- src/mcp_telegram/server.py:28-37 (registration)Dynamically discovers all tool classes (including ListMessages) by inspecting subclasses of ToolArgs in the tools module and creates Tool descriptions for MCP server listing.@cache def enumerate_available_tools() -> t.Generator[tuple[str, Tool], t.Any, None]: for _, tool_args in inspect.getmembers(tools, inspect.isclass): if issubclass(tool_args, tools.ToolArgs) and tool_args != tools.ToolArgs: logger.debug("Found tool: %s", tool_args) description = tools.tool_description(tool_args) yield description.name, description mapping: dict[str, Tool] = dict(enumerate_available_tools())