| name | mattermost |
| description | Read and search Mattermost chat using the `mm` CLI. Use this skill whenever the user mentions Mattermost, chat messages, team chat, unread messages, DMs, channel history, mentions, or wants to catch up on what happened in chat. Also triggers when the user asks about specific people's messages, channel activity, searching for something someone said, or checking notifications. The CLI outputs agent-friendly JSON by default with thread IDs, bot detection, and channel refs - no parsing needed. |
Mattermost CLI (mm)
Read and search Mattermost from the command line. JSON output by default, --human for markdown.
Setup
Check if mm is already available:
mm whoami
If that works, skip to "Start here" below.
If mm is not found, install it. Pick whichever works in your environment:
pip install mattermost-cli
pipx install mattermost-cli
uvx --from mattermost-cli mm
Then authenticate (one-time):
mm login --url https://your.mattermost.server
mm whoami
The login command will prompt for credentials interactively. If your server supports Personal Access Tokens (Profile > Security > Personal Access Tokens in the Mattermost UI), you can skip the prompt:
mm login --url https://your.mattermost.server --token YOUR_TOKEN
For environment variables, multiple servers, and troubleshooting, see references/setup.md.
Start here: mm overview
Always run this first. It returns mentions, unread channels, and active channels in a single call.
mm overview
mm overview --since 1d
The response has three sections:
- mentions - posts that @-mention you, with root message context when it's a reply
- unread - channels with unread messages, sorted by count
- active_channels - channels with recent posts, sorted by recency
Each entry includes a ref field you can pass directly to other commands.
Reading messages
mm messages <channel>
mm messages <channel> --since 2h
mm messages <channel> --threads
mm messages @username
<channel> accepts a name (off-topic), @username for DMs, or a channel ID (for group DMs from overview output).
Threads
Every post includes a thread_id. Use it to read the full conversation:
mm thread <thread_id>
mm thread <thread_id> --limit 0
mm thread <thread_id> --since 1h
Searching and mentions
mm search "deployment issue"
mm search "from:alice in:devops after:2025-01-01"
mm mentions
mm mentions --since 3d
Mentions for replies include a root field with the original message, so you know what "this" or "it" refers to without a follow-up call.
Channel context
mm channel <name>
mm pinned <channel>
mm members <channel>
mm channels --since 6h
mm channels --type dm
People
mm user @someone
Key JSON fields
Every post includes these fields so you can navigate without guesswork:
| Field | What it's for |
|---|
thread_id | Pass to mm thread to read full conversation |
ref | On channel entries; pass to mm messages |
files[].id | On post attachments; pass to mm download |
is_bot / bot_name | Webhook and bot posts are flagged automatically |
root | On reply-mentions; the original message being replied to |
is_reply / reply_count | Thread structure |
reactions | Emoji counts like {"+1": 3, "white_check_mark": 1} |
Bot posts from webhooks automatically extract alert content from Slack-format attachments, so you see the actual alert text instead of empty messages.
Downloading attachments
When a post has attachments, inspect its files array and use the file ID to save the attachment locally:
mm messages incidents --limit 5
mm download abc123def456ghi789jkl012
mm download abc123... def456... --output downloads/
mm download saves each file locally and returns JSON with the original file metadata plus the saved_to path.
Further reading
