# How to Build the Electron MCP Chat App for Windows, macOS, and Linux

> Learn to build the Electron MCP chat app for Windows, macOS, and Linux. Follow simple steps to generate platform-specific installers and get your app running.

- Repository: [AIQL/chat-mcp](https://github.com/ai-ql/chat-mcp)
- Tags: how-to-guide
- Published: 2026-02-23

---

**Run `npm run build-app` after installing Node.js ≥20 and dependencies to generate platform-specific installers in the `artifacts/` folder.**

The **ai-ql/chat-mcp** repository provides an Electron-based desktop chat application that implements the Model Context Protocol (MCP). Building the Electron app for different platforms requires only a single command, but understanding the prerequisites and platform-specific configurations ensures successful compilation for Windows, macOS, and Linux.

## Prerequisites for Building the Electron App

### Common Requirements

Before initiating the build, ensure your environment meets the following baseline requirements:

- **Node.js ≥20** (or any recent LTS version) – Required to execute the `npm` scripts that compile TypeScript and invoke `electron-builder`.
- **npm** – Bundled with Node.js to install project dependencies.
- **Git** – Optional, but necessary if cloning the repository.

### Platform-Specific Build Tools

Certain installer formats require additional system tools:

- **Windows**: No extra tools required for the default `nsis` target.
- **macOS**: Xcode Command Line Tools recommended for code signing.
- **Linux**: To build the `rpm` target on Debian or Ubuntu systems, install the `rpm` package:

```bash
sudo apt-get install rpm

```

## Preparing the Build Environment

### Cloning the Repository and Installing Dependencies

Clone the repository and install all required packages:

```bash
git clone https://github.com/ai-ql/chat-mcp.git
cd chat-mcp
npm install

```

This installs Electron, `electron-builder`, TypeScript compilers, and all runtime dependencies specified in [`package.json`](https://github.com/ai-ql/chat-mcp/blob/main/package.json).

### Configuring the MCP Server Settings

The application expects a [`config.json`](https://github.com/ai-ql/chat-mcp/blob/main/config.json) file in the root of the packaged distribution (alongside the executable). The default configuration resides in [`src/main/config.json`](https://github.com/ai-ql/chat-mcp/blob/main/src/main/config.json) and defines the MCP server connection:

```json
{
  "mcpServers": {
    "everything": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-everything"
      ]
    }
  }
}

```

Edit this file before building to customize server commands, arguments, or add additional MCP servers. The build process copies this configuration into the final bundle.

## Building for All Platforms

### The Build Command and Pipeline

Execute the unified build command defined in [`package.json`](https://github.com/ai-ql/chat-mcp/blob/main/package.json):

```bash
npm run build-app

```

This script performs three operations:
1. Compiles TypeScript sources (`npm run build`).
2. Copies static assets to the output directory.
3. Invokes `electron-builder` to generate platform-specific installers.

### Understanding the electron-builder Configuration

The build pipeline is controlled by the `build` field in [`package.json`](https://github.com/ai-ql/chat-mcp/blob/main/package.json). Key configurations include:

- **Output directory**: Set to `artifacts/` via `build.directories.output`.
- **Windows target**: Uses `nsis` with `oneClick: false` to allow custom installation directories.
- **macOS target**: Generates a signed `dmg` bundle.
- **Linux targets**: Produces `AppImage`, `deb`, and `rpm` packages.

## Platform-Specific Build Outputs

After running `npm run build-app`, the `artifacts/` directory contains the following installers based on your host platform:

### Windows (NSIS Installer)

- **Format**: `aiql-desktop-Setup-1.0.0.exe`
- **Configuration**: Uses `icon.ico` for the application and installer.
- **Behavior**: The `oneClick: false` setting in [`package.json`](https://github.com/ai-ql/chat-mcp/blob/main/package.json) enables a custom installation directory selection rather than a silent install.

### macOS (DMG Bundle)

- **Format**: `aiql-desktop-1.0.0.dmg`
- **Configuration**: Uses `icon.icns` for the application bundle.
- **Signing**: The generated DMG is signed for distribution on macOS systems.

### Linux (AppImage, DEB, and RPM)

- **Formats**:
  - `aiql-desktop-1.0.0.AppImage` (universal binary)
  - `aiql-desktop_1.0.0_amd64.deb` (Debian/Ubuntu package)
  - `aiql-desktop-1.0.0.rpm` (Red Hat/Fedora package)
- **Configuration**: Uses `icon.png` for the application icon.
- **Prerequisites**: For RPM generation on Debian-based systems, ensure the `rpm` package is installed.

## Troubleshooting Common Build Issues

| Issue | Solution |
|-------|----------|
| **Electron download timeout** | Set the `ELECTRON_MIRROR` environment variable to a regional mirror before installing dependencies: `export ELECTRON_MIRROR="https://npm.taobao.org/mirrors/electron/"` |
| **RPM build fails on Ubuntu/Debian** | Install the `rpm` tool: `sudo apt-get install rpm` |
| **AppImage won't execute** | Make the file executable: `chmod +x aiql-desktop-1.0.0.AppImage` |
| **NSIS installer lacks shortcuts** | Verify `electron-builder` version is ≥25 and that `node-notifier` is listed in devDependencies. |

## Summary

- **Prerequisites**: Node.js ≥20, npm, and platform-specific tools (e.g., `rpm` for Linux RPM builds).
- **Configuration**: Edit [`src/main/config.json`](https://github.com/ai-ql/chat-mcp/blob/main/src/main/config.json) before building to customize MCP server settings.
- **Build command**: `npm run build-app` compiles TypeScript and invokes `electron-builder`.
- **Outputs**: Platform-specific installers appear in `artifacts/` (Windows `.exe`, macOS `.dmg`, Linux `.AppImage`/`.deb`/`.rpm`).
- **Icons**: Uses `icon.ico` (Windows), `icon.icns` (macOS), and `icon.png` (Linux).

## Frequently Asked Questions

### What Node.js version is required to build the Electron app?

The build requires **Node.js ≥20** (or any recent LTS version). This ensures compatibility with the TypeScript compiler and `electron-builder` scripts defined in [`package.json`](https://github.com/ai-ql/chat-mcp/blob/main/package.json).

### How do I build only for a specific platform instead of all three?

Run the TypeScript compilation first with `npm run build`, then invoke `electron-builder` with a platform flag. For example, to build only the Linux AppImage: `npx electron-builder --linux appimage`. This overrides the default multi-platform targets defined in [`package.json`](https://github.com/ai-ql/chat-mcp/blob/main/package.json).

### Why does the Linux RPM build fail on Ubuntu or Debian systems?

The `rpm` target requires the `rpm` command-line tool, which is not installed by default on Debian-based distributions. Install it with `sudo apt-get install rpm` before running the build. The DEB and AppImage targets do not require additional system packages.

### Where is the MCP server configuration stored in the packaged app?

The configuration resides in [`src/main/config.json`](https://github.com/ai-ql/chat-mcp/blob/main/src/main/config.json) during development. The build process copies this file to the root of the packaged distribution (alongside the executable). The app reads this [`config.json`](https://github.com/ai-ql/chat-mcp/blob/main/config.json) at runtime to initialize MCP server connections, so you must edit the source file before running `npm run build-app` to customize the bundled configuration.