Skip to main content

Mattermost MCP tool reference

The 121 tools of the built-in Mattermost MCP server, each marked read-only or state-changing. 74 are read-only and 47 change state. The count includes upload_file, which works only on the standalone stdio server, so 120 are usable by agents in Mattermost and over HTTP. The same tools serve agents inside Mattermost and, when an admin enables the HTTP endpoint, external MCP clients. See Mattermost MCP server for connecting a client.

How the tools behave​

  • Every call runs as the signed-in user. A tool returns only what that user can see, and acts only where that user may. Channel membership, team membership, and roles apply.
  • Read-only tools work at every license level. The tools that change state need an Enterprise license. Below that, they're missing from the tool list, and a call returns a licensing message.
  • Approval. For agents inside Mattermost, most read-only tools default to Auto Run (DM) and the rest ask. See Connect agents to MCP servers. External clients aren't covered by Mattermost approval policies. The client decides how to confirm calls.
  • Discovery. With dynamic tool loading on, agents find tools with search_tools and load them with load_tool, instead of receiving every schema at once.
  • Posts the server creates are marked as AI-generated.
  • Plugin tools aren't listed here. Tools from plugin-registered MCP servers are configured separately. See Connect agents to MCP servers.
  • Development tools. Three more tools, create_post_as_user, create_user, and create_team, exist only on the standalone development server. They're not available in the embedded server or over HTTP.

Posts and messages​

ToolTypeWhat it does
read_postRead-onlyRead a specific post and its thread from Mattermost
get_post_infoRead-onlyGet metadata and channel/team context for a single post (without the thread)
list_pinned_postsRead-onlyList the pinned posts in a channel
list_saved_postsRead-onlyList your saved (flagged) posts, optionally scoped to a channel or team
create_postChanges statePost a message in a channel or reply in a thread, optionally with inline text files. Needs the channel and team display names as a safety check
dmChanges stateSend a direct message to a user, optionally with inline text files. Without a username, it messages you
group_messageChanges stateSend a message to a group conversation with at least two other users, optionally with inline text files
update_postChanges stateEdit the message text of an existing post
delete_postChanges stateDelete (soft-remove) a post by ID
pin_postChanges statePin a post to its channel
unpin_postChanges stateUnpin a post from its channel
save_postChanges stateSave (flag) a post for yourself so you can find it later
acknowledge_postChanges stateAdd your acknowledgement to a post that requests one

Scheduled posts, reminders, and drafts​

ToolTypeWhat it does
list_scheduled_postsRead-onlyList your pending scheduled posts for a team
list_draftsRead-onlyList your unsent message drafts for a team, including direct and group message drafts
create_scheduled_postChanges stateSchedule a message to send to a channel (or thread) at a future time
update_scheduled_postChanges stateChange a pending scheduled post's text or send time
delete_scheduled_postChanges stateCancel a pending scheduled post
set_post_reminderChanges stateSet yourself a reminder about a post at a given time
create_draftChanges stateSave a draft in a channel or thread for you to review and send yourself. Nothing is posted
delete_draftChanges stateDelete your draft in a channel (or thread)

Reactions and emoji​

ToolTypeWhat it does
get_post_reactionsRead-onlyList the emoji reactions on a post and who reacted
list_custom_emojiRead-onlyList the server's custom emoji
search_custom_emojiRead-onlySearch custom emoji by name
add_reactionChanges stateAdd an emoji reaction to a post
remove_reactionChanges stateRemove your emoji reaction from a post

Threads, mentions, and unread state​

ToolTypeWhat it does
get_threadsRead-onlyGet your threads inbox for a team: followed and unread threads
get_mentionsRead-onlyGet recent posts containing unread at-mentions of you (Recent Mentions)
get_unread_countsRead-onlyGet your unread message, mention, and thread counts across teams, or for one team
get_channel_unreadRead-onlyGet unread message and mention counts for one channel
get_posts_around_unreadRead-onlyGet the posts surrounding your last-read line in a channel
mark_channel_readChanges stateMark a channel viewed/read to clear its unread badge
mark_channels_viewedChanges stateMark one or more channels viewed/read (bulk)
mark_post_unreadChanges stateMark a channel unread starting at a specific post
set_thread_followChanges stateFollow or unfollow a thread

Channels​

ToolTypeWhat it does
read_channelRead-onlyRead recent posts from a Mattermost channel, with history pagination
get_channel_infoRead-onlyGet channel details by ID or name. A name that matches several teams returns every match
get_channel_statsRead-onlyGet a channel's statistics: member, guest, pinned-post, and file counts
get_channel_member_countsRead-onlyGet member counts for a batch of channels
search_channelsRead-onlySearch channels by term
list_team_channelsRead-onlyList a team's public and private channels
list_archived_channelsRead-onlyList a team's archived (deleted) channels
get_user_channelsRead-onlyGet the channels the signed-in user belongs to, including direct and group messages
create_channelChanges stateCreate a public or private channel in a team
update_channelChanges stateUpdate a channel's display name, URL name, header, or purpose
archive_channelChanges stateArchive (soft-delete) a channel
restore_channelChanges stateRestore (unarchive) an archived channel
convert_channel_privacyChanges stateConvert a channel between public and private

Channel members and settings​

ToolTypeWhat it does
get_channel_membersRead-onlyGet a channel's members, with paging
get_channel_memberRead-onlyGet your (or a given user's) membership in a channel: roles, mute, last-viewed
get_channel_members_by_idsRead-onlyGet membership records for a specific set of users in a channel
get_channel_members_by_statusRead-onlyGet a channel's members ordered by presence status (online first)
get_user_channel_membershipsRead-onlyGet a user's channel membership records within a team (roles per channel)
get_users_not_in_channelRead-onlyGet team members who are not in a channel (candidates to add)
search_users_in_channelRead-onlySearch for users within (or excluding) a channel
list_sidebar_categoriesRead-onlyList your sidebar categories and their channels for a team
add_channel_memberChanges stateAdd a user to a channel (channel membership)
add_channel_membersChanges stateAdd several users to a channel (bulk; pairs with add_channel_member)
remove_channel_memberChanges stateRemove a user from a channel
set_channel_muteChanges stateMute or unmute a channel for yourself
set_channel_favoriteChanges stateAdd or remove a channel from your favorites
update_channel_notify_propsChanges stateSet your per-channel notifications (desktop/push level, and unread/mute level)

Channel bookmarks​

ToolTypeWhat it does
list_channel_bookmarksRead-onlyList a channel's bookmarks (pinned links and files)
create_channel_bookmarkChanges stateAdd a link or file bookmark to a channel
update_channel_bookmarkChanges stateEdit a channel bookmark (name, link, or emoji)
delete_channel_bookmarkChanges stateRemove a channel bookmark

Users and profiles​

ToolTypeWhat it does
get_meRead-onlyGet the profile of the signed-in user
get_userRead-onlyGet a single user's full profile by ID
get_user_by_usernameRead-onlyGet a user's profile by username
get_user_by_emailRead-onlyGet a user's profile by email
get_users_by_idsRead-onlyBatch-fetch user profiles by a list of IDs
get_users_by_usernamesRead-onlyBatch-fetch user profiles by a list of usernames
get_user_statsRead-onlyGet the server's total user count
get_user_cpa_valuesRead-onlyGet a user's Custom Profile Attribute (CPA) values
list_cpa_fieldsRead-onlyList the server's Custom Profile Attribute (CPA) field definitions
search_usersRead-onlyFind users by username, email, or name
update_userChanges stateUpdate profile fields (nickname, first name, last name, position)

Status and presence​

ToolTypeWhat it does
get_user_statusRead-onlyGet a user's presence: online, away, do not disturb (dnd), or offline
get_users_statusesRead-onlyBatch-fetch presence for a list of user IDs
get_user_custom_statusRead-onlyGet a user's custom status (emoji, text, expiry)
set_statusChanges stateSet your own presence: online, away, offline, or do not disturb (dnd)
set_dndChanges stateSet your own Do Not Disturb (dnd) status, optionally until a given time

Teams and team members​

ToolTypeWhat it does
get_team_infoRead-onlyGet team details by ID or name
get_team_membersRead-onlyGet a team's members, with paging
get_team_memberRead-onlyGet a user's team membership record (roles)
get_team_statsRead-onlyGet a team's member counts (total and active)
get_user_teamsRead-onlyGet the teams a user belongs to
get_users_in_teamRead-onlyGet the member profiles of a team
get_users_not_in_teamRead-onlyGet users who are not members of a team
get_new_users_in_teamRead-onlyGet the most recently joined members of a team
get_dm_common_teamsRead-onlyGet teams shared by all members of a direct message (DM) or group message (GM) channel
search_teamsRead-onlySearch teams by name or display name
search_users_in_teamRead-onlySearch for users within (or excluding) a team
add_team_memberChanges stateAdd a user to a team (team membership)
add_team_membersChanges stateAdd several users to a team (bulk)
remove_team_memberChanges stateRemove a user from a team
update_teamChanges stateUpdate team fields (display name, description, open-invite setting)
invite_users_to_teamChanges stateEmail-invite users to a team
invite_users_to_team_and_channelsChanges stateEmail-invite users to a team and specific channels

Files​

ToolTypeWhat it does
read_fileRead-onlyRead the text of a file attachment by file ID, with extracted text for PDF and Office documents and paged reads for large files
get_file_infoRead-onlyGet metadata for a single file/attachment
get_post_filesRead-onlyGet the file attachments on a post (metadata per file)
get_file_linkRead-onlyGet a public link to a file. The link bypasses normal file access checks
search_filesRead-onlySearch file attachments by filename/content within a team
upload_fileChanges stateUpload a file from a local path or URL. Listed on every server, but works only on the standalone stdio server (local access mode). Elsewhere it returns an error. Use files on create_post instead
ToolTypeWhat it does
search_postsRead-onlySearch posts by keyword, with semantic results added when semantic search is on. Accepts team, channel, author, and date filters

Integrations​

ToolTypeWhat it does
get_botRead-onlyGet a single bot account's details
list_botsRead-onlyList bot accounts
list_incoming_webhooksRead-onlyList incoming webhooks
list_outgoing_webhooksRead-onlyList outgoing webhooks for a team or channel

Groups​

ToolTypeWhat it does
get_group_infoRead-onlyGet a group's metadata
list_groupsRead-onlyList or search custom and LDAP-synced groups
get_user_groupsRead-onlyGet the groups a user belongs to
get_channel_groupsRead-onlyGet the groups synced to a channel
get_team_groupsRead-onlyGet the groups synced to a team
get_users_in_group_channelsRead-onlyGet the members of given group-message (GM) channels

Roles and permissions​

ToolTypeWhat it does
get_roleRead-onlyGet a role definition and its permission set
get_channel_moderationsRead-onlyGet a channel's moderation settings (which actions members and guests may take)
update_channel_member_rolesChanges statePromote or demote a channel member to or from channel admin
update_team_member_rolesChanges statePromote or demote a team member to or from team admin

Agents​

ToolTypeWhat it does
list_agentsRead-onlyList the agents available to the user, with each agent's ID, display name, and username