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

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:

sudo apt-get install rpm

Preparing the Build Environment

Cloning the Repository and Installing Dependencies

Clone the repository and install all required packages:

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.

Configuring the MCP Server Settings

The application expects a config.json file in the root of the packaged distribution (alongside the executable). The default configuration resides in src/main/config.json and defines the MCP server connection:

{
  "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:

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. 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 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 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.

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.

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 during development. The build process copies this file to the root of the packaged distribution (alongside the executable). The app reads this 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}