mcp-server-mattermost

get_channel_messages

Read-onlyIdempotent

Retrieve channel messages by browsing recent history, viewing unread posts, or syncing edits since a timestamp. Choose the mode that fits your need.

Instructions

Get messages from a channel — recent history, the user's unread window, or posts changed since a watermark.

Three mutually-exclusive modes. Pick by user intent:

"Show last N" / "what's in this channel" → default (page, per_page). Reverse-chronological. truncated=True ⇒ more posts exist; paginate.
"What did I miss" → unread_only=True. The user's unread window anchored at last_viewed_at, with limit_before context posts. Quirk: on a never-viewed channel (last_viewed_at == 0) order is empty even when unread_msg_count > 0 — call mark_channel_viewed once to bootstrap.
"Sync everything since " → since=<unix_ms>. Posts with update_at > since, including edits of older posts and tombstones (delete_at != 0, empty message). Server caps at 1000; on truncated=True step the watermark forward in smaller windows.

Returns {order, posts, truncated}. posts may contain more entries than order (root posts pulled in by thread replies). System posts (type starts with "system_") appear in unread_only/since responses but are NOT counted in unread_msg_count.

For keyword search use search_messages; for full threads use get_thread.

Input Schema

TableJSON Schema

Name	Required	Description
`page`	No	Page number (0-indexed)
`since`	No	Unix timestamp in milliseconds (>= 10^12, i.e. >= 2001-01-01); return posts modified after this time. Mutually exclusive with unread_only and pagination. Use ChannelWithUnreads.last_viewed_at from list_my_channels.
`per_page`	No	Results per page
`channel_id`	Yes	26-character channel identifier (e.g., 'o5w8h47pdfbzjc4d8w7dhnhren')
`limit_after`	No	In unread_only mode: unread posts to return (1-200)
`unread_only`	No	Return only the user's unread window via /posts/unread
`limit_before`	No	In unread_only mode: read context posts before the first unread (max 200)
`collapsed_threads`	No	Set True only if the user has CRT (Collapsed Reply Threads) enabled. Team default is CRT off — leave False unless you know otherwise. Requires unread_only=True or since=<ms>; the default /posts endpoint rejects CRT-aware queries.

Output Schema

TableJSON Schema

Name	Required	Description
`order`	Yes	Post IDs in display order
`posts`	Yes	Map of post ID to Post object
`truncated`	No	True when the response hit a Mattermost response cap — more posts exist beyond this batch
`next_post_id`	No	Next post ID for pagination
`prev_post_id`	No	Previous post ID for pagination

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.6.1Sep 10, 2026

changedOutput schema / properties / posts / additionalProperties / required

Previous value: -[
-  "id",
-  "create_at",
-  "update_at",
-  "delete_at",
-  "edit_at",
-  "user_id",
-  "channel_id",
-  "root_id",
-  "original_id",
-  "message",
-  "type",
-  "hashtags",
-  "file_ids",
-  "pending_post_id",
-  "is_pinned"
-]New value: +[
+  "id",
+  "create_at",
+  "update_at",
+  "delete_at",
+  "edit_at",
+  "user_id",
+  "channel_id",
+  "root_id",
+  "original_id",
+  "message",
+  "type",
+  "hashtags",
+  "pending_post_id",
+  "is_pinned"
+]

First observedv0.5.1Jul 29, 2026

TDQS

A5/5.0

Behavior5/5

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

Annotations already declare readOnlyHint and idempotentHint, but the description goes far beyond them: it discloses the never-viewed-channel quirk, tombstone/edited-post behavior in since mode, server cap of 1000 with truncated=True pagination advice, posts/order mismatch, and system-post exclusion from unread_msg_count. There is no contradiction with 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 long but warranted: it front-loads the one-sentence summary, then uses clear labeled bullets for the three modes and a short return-shape section. Every sentence adds operational value, and the structure makes the complex behavior scannable.

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?

The description covers mode selection, behavioral quirks, return semantics, pagination strategy, and alternatives. With an output schema present and sibling tools listed, nothing needed to call this tool correctly is missing.

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

Parameters5/5

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

Although schema coverage is 100%, the description adds crucial semantics: it explains how page/per_page relate to reverse-chronological pagination, what unread_only anchors to (last_viewed_at, limit_before), how since differs from simple filtering (includes edits and tombstones), and the CRT requirement. This materially improves an agent's ability to choose and set parameters correctly.

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 opens with a specific verb and resource: 'Get messages from a channel.' It then names three distinct modes with explicit triggers, and closes by distinguishing itself from search_messages (keyword search) and get_thread (full threads). This fully disambiguates it from sibling tools.

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?

The description explicitly maps user intent to each mode: 'Show last N' → default, 'What did I miss' → unread_only, 'Sync everything since' → since. It also gives when-not-to-use guidance by naming alternatives for keyword search and threads, and notes CRT constraints. This is model usage guidance.

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