conarti/mattermost-mcp

MCP Server for the Mattermost API, enabling Claude and other MCP clients to interact with Mattermost workspaces.
Quick Start
Using npx (recommended)
Using environment variables
Using CLI arguments
Installation
Option 1: npx (no installation needed)
Option 2: Global installation
Option 3: Clone and build
Browser sign-in (no token)
MATTERMOST_TOKEN is optional. Without a token the server signs in to Mattermost through a visible Chromium window and keeps the session token for you. With MATTERMOST_TOKEN set, the server works as before (static mode): no browser window, no Chromium download, and ~/.config/mattermost-mcp is not created.
First sign-in
1. Configure the server with MATTERMOST_URL and MATTERMOST_TEAM_ID only, without a token (see Claude Code Integration and opencode below).
2. Call any Mattermost tool. The server opens a Chromium window with the Mattermost login page.
3. Sign in the way you usually do (password, SSO, MFA). You have up to 5 minutes.
4. The window closes by itself as soon as the session is valid, and the tool call returns its result.
While the call waits, the server sends progress notifications every 10 seconds, so clients that show MCP progress display the current step. The window opens only from a tool call: never at server startup and never from background monitoring.
Chromium is downloaded automatically
No manual installation is needed.
- On the first sign-in the server downloads Chromium and ffmpeg for Playwright 1.63.0 (about 183 MiB on macOS arm64) into ~/.config/mattermost-mcp/browsers. The client shows the progress as Downloading Chromium for Mattermost sign-in: 40% of 182.1 MiB, and for the small ffmpeg archive that follows as Downloading Chromium for Mattermost sign-in: FFmpeg 50% of 1 MiB.
- The first call takes longer: the download is limited to 10 minutes, and the 5 minutes for sign-in start after the download has finished.
- After an update of this package to a version with another Playwright version, the matching Chromium build is downloaded the same way.
- Behind a proxy or with a download mirror, set HTTPS_PROXY, HTTP_PROXY, NO_PROXY, PLAYWRIGHT_DOWNLOAD_HOST or PLAYWRIGHT_DOWNLOAD_CONNECTION_TIMEOUT in the env of the MCP server entry.
- The shared Playwright cache (~/Library/Caches/ms-playwright on macOS) is not used: Playwright installations in other projects remove builds that no project references.
- If the download fails, the error contains the reason and a manual command as a fallback, see Browser sign-in problems.
- On Linux without the system libraries for Chromium, a one-time install-deps command is needed, see Browser sign-in problems.
- Keep this package up to date: each release pins a Playwright version, and newer versions bring Chromium builds with security fixes.
- Keep PLAYWRIGHT_DOWNLOAD_HOST on https:// and do not disable TLS certificate checks for the download (for example with NODE_TLS_REJECT_UNAUTHORIZED=0): the downloaded Chromium later holds your Mattermost session.
What is stored where
Everything lives in ~/.config/mattermost-mcp/ (permissions 0700):
- browsers/: Chromium builds for the sign-in window.
- profile/: the Chromium profile with the Mattermost session. It is as sensitive as the token because cookies in it are not encrypted. Exclude it from dotfiles sync and backups.
- token: the session token (permissions 0600), bound to the server address.
- login.lock and login.lock.break: short-lived lock files that let several server processes share one sign-in window.
- tmp/: temporary files of the Chromium download, removed after the installation.
The server refuses to use the directory if ~/.config or your home directory belongs to another user or is writable by group or others without the sticky bit, see [STATE_DIRECTORY_UNSAFE] in Browser sign-in problems.
Security of the sign-in window
- The Chromium window runs with the Chromium sandbox enabled, because it renders Mattermost content written by other users. Set MATTERMOST_MCP_DISABLE_CHROMIUM_SANDBOX=1 in the env of the MCP server entry only if the sandbox is unavailable on your system ([BROWSER_SANDBOX_UNAVAILABLE]). The server then logs a warning each time it opens the window.