SuperAPI AI Directory
Partner with us中文AI newsFavorites
All toolsAI developer platformsmattermost-mcp

mattermost-mcp

Mattermost API integration: list channels, read and post messages, manage threads and reactions, and monitor topics.

Open website

About this tool

Purpose

Mattermost MCP server provides an MCP interface for the Mattermost API, enabling Claude and other MCP clients to interact with Mattermost workspaces.

Main capabilities

  • List channels (supports pagination, whether to include private channels and direct messages)
  • Read channel message history (supports by count, page number, date range, cursor pagination)
  • Read thread replies (including the root post)
  • Post and edit messages
  • Manage threads and emoji reactions
  • Download post attachments (can specify save path, images can be returned inline)
  • Topic monitoring: monitor specified channels on a cron schedule for topics of interest, and send notifications when relevant topics are discussed

Usage

Supports three ways to run:

  1. Use npx (recommended, no installation required)
  2. Global installation
  3. Clone and build

Configuration priority from highest to lowest is: CLI arguments (--url, --token, --team-id), environment variables (MATTERMOST_URL, MATTERMOST_TOKEN, MATTERMOST_TEAM_ID), config.local.json (local override, gitignored), config.json (default configuration).

Browser login (no token required)

MATTERMOST_TOKEN is optional. When no token is set, the server logs in to Mattermost through a visible Chromium window and saves the session token. When a token is set, static mode is used: no browser window is opened, Chromium is not downloaded, and ~/.config/mattermost-mcp is not created.

Configuring only MATTERMOST_URL and MATTERMOST_TEAM_ID (without setting a token) is enough to use browser login. When any Mattermost tool is called, the server opens the Chromium login page, and the user logs in in the usual way (password, SSO, MFA), with a 5-minute time limit. Once the session is valid, the window closes automatically and the tool call returns its result. During the wait, a progress notification is sent every 10 seconds. The window is opened only during tool calls, not at server startup or during background monitoring.

Chromium automatic download: on first login, the server downloads Chromium and ffmpeg for Playwright 1.63.0 (on macOS arm64 about 183 MiB) to ~/.config/mattermost-mcp/browsers. The first call takes a long time: the download has a 10-minute time limit, and the 5-minute login starts after the download completes. In proxy or mirror environments, you can set HTTPS_PROXY, HTTP_PROXY, NO_PROXY, PLAYWRIGHT_DOWNLOAD_HOST, or PLAYWRIGHT_DOWNLOAD_CONNECTION_TIMEOUT. A shared Playwright cache is not used. When the download fails, the error message includes the reason and a manual command. If Linux is missing Chromium system libraries, the install-deps command must be run once.

Storage location

Everything is located in ~/.config/mattermost-mcp/ (permissions 0700):

  • browsers/: the Chromium build for the login window
  • profile/: the Chromium profile containing the Mattermost session (as sensitive as a token, cookies are not encrypted, should be excluded from dotfiles syncing and backups)
  • token: the session token (permissions 0600), bound to the server address
  • login.lock and login.lock.break: short-lived lock files that allow multiple server processes to share one login window
  • tmp/: temporary files for the Chromium download, deleted after installation

If ~/.config or the home directory belongs to another user, or is writable by group/other users and has no sticky bit, the server refuses to use that directory.

Login window security

The Chromium window has the sandbox enabled because it renders Mattermost content written by other users. Set MATTERMOST_MCP_DISABLE_CHROMIUM_SANDBOX=1 only when the system does not support the sandbox; in that case a warning is logged every time the window is opened. MATTERMOST_URL should use an https:// address; when using http:// and the host is not localhost, 127.0.0.1, or [::1], a warning is logged at startup.

Reset session

Remove only the session (the next tool call reopens the login window) or remove everything (including Chromium, which will be downloaded again on the next login). The two commandsExecuting while the login window is open is safe.

Multiple clients

Clients such as Claude Code and opencode on the same machine share one token file and one login window. When multiple clients need to log in at the same time, only one window is opened, and all waiting calls continue after login.

Background topic monitoring

Background monitoring never opens a window. When the server starts, if there is no saved session:

  • If monitoring.userId or monitoring.notificationChannelId is not set, monitoring cannot look them up, and the schedule will not start. You need to call mattermost_run_monitoring: it will log in on demand, start the schedule, and run monitoring once. Logging in through other tools will not start the schedule; afterward you need to call mattermost_run_monitoring or restart the server.
  • If both are set, the schedule starts immediately, and runs before the first login are skipped with [AUTHENTICATION_REQUIRED].

Client timeouts

The first tool call may take several minutes (Chromium download plus up to 5 minutes for login). Progress notifications every 10 seconds can keep the call alive for clients that pass a progressToken and reset their timeout accordingly. opencode requires mcp.mattermost.timeout and experimental.mcp_timeout to be set to 360000 (6 minutes). Clients that do not pass a progressToken may cancel the first call during the download; the download will stop and restart on the next call.

Other limitations

  • One Mattermost server per OS user. Token files for other servers are ignored. Addresses are normalized before comparison; /api/v4, trailing slashes, and host case do not matter.
  • When clients with different MATTERMOST_URLs log in at the same time, waiting calls receive LOGIN_NOT_COMPLETED, and the window for the second server opens only when a tool is called again.
  • Do not enable DEBUG=pw:* for the server; Playwright debug output prints cookies.
  • Windows is not supported.

Tool parameter summary

  • List channels: limit (default 100), page (default 0), include_private (default false)
  • Get channel history: channel_id (required), limit (if unspecified or 0, return all), page (default 0, used only when limit>0), since_date, before_date, before_post_id, after_post_id
  • Posts with attachments include file_ids and files (id, name, extension, size, mime_type; images also have width/height) in mattermost_get_channel_history and mattermost_get_thread_replies (including root_post)
  • Edit post: mattermost_edit_post accepts post_id and message. Only the post author or someone with permission can edit it; 403 returns a hint, and other errors return the server's original text. Both tools reject post_ids that are not 26 characters before sending the request.
  • Download file: file_id (required), output_path (if not set, save to the system temporary directory mattermost-mcp/{file_id}_{name}; if it is a directory or ends with / or , save into it; other paths are treated as file paths; ~ expands to the home directory; existing files are overwritten), inline (default false, only image/png, image/jpeg, image/gif, image/webp and no more than 1 MB are returned inline)

Obtaining credentials

  • The Mattermost API URL is usually https://your-mattermost-domain.com/api/v4
  • Personal access token: Account Settings > Security > Personal Access Tokens > Create Token
  • Team ID: Open the team in Mattermost and use the browser developer tools (F12) to inspect network API calls related to teams/ in Network, or use the Mattermost API

Troubleshooting

  • Missing configuration error: Ensure the Mattermost URL and team ID are provided via CLI arguments, environment variables, or a configuration file. A token is not required.
  • Permission error: Confirm that the Mattermost user (the token owner or the browser-logged-in user) has the necessary permissions, that the token is correct, and that the URL and team ID are correct. To switch users for browser login, reset the session and then call the tool again.
  • Browser login issues: Errors begin with a bracketed code.
    • [BROWSER_INSTALLATION_FAILED]: Automatic Chromium download failed, and the error includes the reason. You can manually install Chromium as a fallback. If the error mentions an active __dirlock, wait for other installations to finish or delete it as described in the error text.
    • [BROWSER_SYSTEM_DEPENDENCIES_MISSING] (Linux): One-time installation of system libraries is required.
    • [BROWSER_SANDBOX_UNAVAILABLE] (Linux): Enable the sandbox when possible; otherwise set MATTERMOST_MCP_DISABLE_CHROMIUM_SANDBOX=1.
    • [LOGIN_WINDOW_CLOSED], [LOGIN_TIMEOUT], [LOGIN_NOT_COMPLETED]: The window was closed, login timed out, or login from another client was not completed; call the tool again.
    • [LOGIN_PROFILE_BUSY]: Another Chromium window is using the login profile; close it and retry.
    • [AUTHENTICATION_REQUIRED] (monitoring logs): Background monitoring does not open a login window; call any Mattermost tool to log in.
    • [STATE_DIRECTORY_UNSAFE]: The state directory or the permissions of ~/.config or the home directory are unsafe; fix them as described in the error text.

Applicable Scenarios

Suitable for users who need to operate a Mattermost workspace in MCP clients such as Claude, including reading channel messages, posting content, managing threads, downloading attachments, and monitoring specific topics on a schedule and receiving notifications.

Limitations

  • Windows is not supported.
  • The first call in browser login mode takes a long time and depends on Chromium download.
  • The session directory contains unencrypted cookies, so it must be protected.
  • Each OS user corresponds to only one Mattermost server.
  • Some clients may cancel the first call due to a timeout.

Related tools

Browse category