# Mattermost Desktop: Electron client for Windows, Mac and Linux

> Mattermost Desktop is an open source Electron app that wraps the Mattermost collaboration platform with native notifications, multi-server support and deep linking. It requires an existing self-hosted or cloud Mattermost server and is not a standalone messaging tool.

**mattermost/desktop** — Mattermost Desktop application for Windows, Mac and Linux

- Repository: https://github.com/mattermost/desktop
- Stars: 2,269 · Forks: 985
- Language: TypeScript
- License: Apache-2.0
- Published: 2026-10-11 · Updated: 2026-10-11 · Language: en
- Canonical page: https://hysenlabs.com/projects/mattermost-desktop

## Electron shell over the Mattermost web app, not a standalone messenger

Mattermost Desktop is an Electron application wrapping the Mattermost web interface, not a separate messaging backend. It requires an existing Mattermost server, either self-hosted or cloud-hosted, and the app connects to that server on first launch. Without a server URL, the app has nothing to show.

Originated as the project 'electron-mattermost' by Yuya Ochiai before moving under the Mattermost organisation, the desktop app now sits as an official component alongside the server and mobile clients. Its value proposition compared to a browser tab is platform integration: native OS notifications, a persistent process that runs in the background, badge counts visible in the taskbar or dock, and deep links that open Mattermost URLs directly in the app rather than routing them to the browser.

Teams that already use Mattermost in a browser and find the notification permissions adequate may not gain enough from the install to justify it. For teams managing multiple Mattermost servers, the server dropdown in the desktop app consolidates them in one window without multiple browser tabs.

## Server dropdown, Channels/Boards/Playbooks tabs, deep linking and badge counts

Four interface features differentiate the desktop app from a browser tab. First is the server dropdown, which lets users switch between multiple Mattermost servers without opening separate windows. Second is a tab structure with dedicated tabs for Channels, Boards and Playbooks, matching the organisation of the Mattermost platform.

Deep linking is the third addition. Opening a mattermost:// URL on a machine with the desktop app installed routes the link into the app rather than to the browser, which preserves context when links arrive from outside the app, for example in a calendar invite or an email.

Badge counts for unread channels and mentions appear in the system tray or dock icon, giving visibility into activity without switching windows. Combining that with background running, where the app remains in memory after the main window is closed, means notifications arrive even when the user is not actively looking at the app.

## Downloading and entering the server URL on first launch

Installation starts with a download from either the official downloads page at mattermost.com/download/#mattermostApps or the GitHub releases page. Depending on the platform, the download is an installer or a compressed archive. Running the installer or extracting the archive and launching the resulting application covers the install step.

First launch asks for a server name and a server URL. According to the README, the URL follows the pattern:

```
https://mattermost.example.com
```

Entering the URL connects the app to that Mattermost instance. Detailed platform-specific installation guides are available at docs.mattermost.com/install/desktop-app-install.html. For any step that is not in the README, the documentation site is the reference.

## Config in %APPDATA%\Mattermost on Windows and ~/.config/Mattermost on Linux

Configuration is stored in Electron's userData directory, and the location differs by operating system. On Windows, data lands in %APPDATA%\Mattermost. On macOS, it goes to ~/Library/Application Support/Mattermost. Linux stores it at ~/.config/Mattermost.

For deployments where the default location does not work, each platform supports a --data-dir argument that redirects configuration to a custom path. The README gives the exact commands:

On Windows:

```bash
Mattermost.exe --args --data-dir C:\my-mattermost-data
```

On macOS:

```bash
open /Applications/Mattermost.app/ --args --data-dir ~/my-mattermost-data/
```

On Linux, the binary name comes from the desktopName field in package.json, which is com.Mattermost.Desktop:

```bash
./com.Mattermost.Desktop --args --data-dir ~/my-mattermost-data/
```

All 3 commands redirect only configuration and stored data, not the application files themselves. The README does not document any environment variables that affect configuration beyond --data-dir.

## Silent Windows installer and pre-configured server URL for enterprise rollout

Standard installs ask users to enter a server URL on first launch, which works for individual setups but creates friction in managed enterprise deployments. Mattermost provides a deployment path that bypasses this: a custom app can be built and distributed with the server URL and other settings pre-configured, and the Windows version of the installer supports silent installation.

According to the README, a guide for this workflow is at docs.mattermost.com/deployment/desktop-app-deployment.html. That guide covers how to customise and distribute your own Mattermost Desktop app, including how to distribute the Windows desktop app silently to end users.

This path matters for IT departments rolling out Mattermost across a fleet without expecting users to know the server URL. The README does not detail the customisation steps in its own text; the deployment documentation is the starting point.

## Building from source: Node 24, three webpack targets, and the Makefile package discrepancy

Building from source requires Node.js 24.0.0 or later, as specified in the engines field of package.json. Installing dependencies uses a custom npm ci command that skips the Playwright browser download, which is only needed for end-to-end tests:

```bash
PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 npm ci
```

Building the app runs 3 webpack configurations in parallel, covering Electron's main process, the preload script and the renderer. Running npm run build from package.json triggers all 3. Separate test scripts cover unit tests with Jest and end-to-end tests with Playwright, and the check script runs lint, type checking and unit tests together.

One discrepancy in the Makefile is worth noting: the package target carries the comment 'Generates packages for all environments', but its only dependency is package-linux-deb. No macOS or Windows packaging target appears in the Makefile. The Linux .deb path requires dpkg-sig and gpg to be available for signing, and the Makefile exits with code 128 if either is missing or if GPG_KEY_ID is undefined.

## AGENTS.md in the repository and what the repository layout shows

AGENTS.md appears at the top level of the repository alongside the standard CONTRIBUTING.md, SECURITY.md and TESTING.md files. Its presence is unusual; most open source projects do not include a file with that name, and the README makes no reference to it, leaving its contents undocumented from the main entry point.

Other files visible in the top-level listing point to a mature build and deployment infrastructure. A .gitlab-ci.yml exists alongside the primary .github/ directory, showing CI on two platforms. A fastlane/ directory, normally associated with iOS and Android deployment, appears here for a desktop application. A patches/ directory indicates vendored dependencies with modifications applied by patch-package, which the postinstall script in package.json runs on every npm install.

A push to the master branch last occurred on 2026-09-28. Mattermost Desktop is distributed under the Apache-2.0 licence; the text is in LICENSE.txt at the repository root, and NOTICE.txt carries attribution for third-party components as required by the Apache 2.0 terms.

## Conclusion

Mattermost Desktop is worth adopting for teams running their own Mattermost server who need desktop notifications, multi-server management or deep links. A browser tab with notification permissions granted covers the same Mattermost interface without the install; choose the desktop app when that is not enough. For enterprise rollout, the silent Windows installer with a pre-configured server URL is documented at docs.mattermost.com/deployment/desktop-app-deployment.html. Building from source requires Node 24; the Makefile's package target builds only a Linux .deb despite claiming all environments in its comment.

## FAQ

### Do I need a Mattermost server to use Mattermost Desktop?

Yes. Mattermost Desktop is a client that connects to an existing Mattermost server. On first launch the app asks for a server name and URL; without a server, the app has nothing to display.

### Where does Mattermost Desktop store its configuration?

Configuration is stored in Electron's userData directory: %APPDATA%\Mattermost on Windows, ~/Library/Application Support/Mattermost on macOS, and ~/.config/Mattermost on Linux. A custom path can be set with the --data-dir argument.

### How do I install Mattermost Desktop?

Download a file from mattermost.com/download/#mattermostApps or from the GitHub releases page, run the installer or unzip the archive, and launch the application. Detailed guides are at docs.mattermost.com/install/desktop-app-install.html.

### Can I deploy Mattermost Desktop silently across a Windows fleet?

According to the README, the official Windows Desktop App can be distributed silently with a pre-configured server URL. The deployment guide is at docs.mattermost.com/deployment/desktop-app-deployment.html.

### What Node.js version is required to build Mattermost Desktop from source?

The engines field in package.json requires Node.js 24 or later. Installing dependencies uses PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 npm ci to skip the Playwright browser download.

## Sources

- [Issues](https://github.com/mattermost/desktop/issues)
- [License: Apache-2.0](https://github.com/mattermost/desktop/blob/master/LICENSE)
- [mattermost/desktop on GitHub](https://github.com/mattermost/desktop)
- [README](https://github.com/mattermost/desktop/blob/master/README.md)
- [Releases](https://github.com/mattermost/desktop/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/mattermost-desktop