# Platform-Specific Requirements for Running ChatMCP on Linux: Complete Dependency Guide

> Learn the platform-specific requirements for running ChatMCP on Linux. Discover essential native library dependencies like FUSE2 GTK3 EGL OpenGL and SQLite3 needed for seamless operation.

- Repository: [刀刀/chatmcp](https://github.com/daodao97/chatmcp)
- Tags: how-to-guide
- Published: 2026-02-28

---

**ChatMCP requires native libraries including FUSE2 for AppImage execution, GTK3 for UI rendering, EGL/OpenGL for graphics acceleration, and SQLite3 for local data persistence that are not bundled with the Flutter runtime and must be installed separately on Linux systems.**

ChatMCP is a cross-platform Flutter desktop client for the Model Context Protocol (MCP) hosted at `daodao97/chatmcp`. While the repository provides pre-built AppImage and DEB packages, the Linux build depends on several system-level libraries that must be present on the host machine to handle window management, hardware-accelerated rendering, and local database operations according to the source code in [`README.md`](https://github.com/daodao97/chatmcp/blob/main/README.md) and the CI configuration in [`.github/workflows/build.yml`](https://github.com/daodao97/chatmcp/blob/main/.github/workflows/build.yml).

## Core Runtime Dependencies for ChatMCP Linux Builds

### AppImage and FUSE2 Requirements

The AppImage distribution requires **libfuse2** to mount the bundled SquashFS filesystem. Without this package, the single-file executable cannot unpack its contents and will fail to start immediately. This dependency is explicitly listed in the repository's Linux requirements section.

### Graphics and UI Toolkit Dependencies

ChatMCP relies on **GTK 3** (`libgtk-3-0`) as the underlying windowing toolkit that Flutter's Linux embedder uses for native window management and widget rendering. Hardware-accelerated rendering requires specific EGL and OpenGL ES libraries that differ slightly between Ubuntu versions:

- **Ubuntu 22.04**: `libegl1-mesa`, `libgles2`, `libgl1-mesa-dri`, `libglx-mesa0`
- **Ubuntu 24.04**: `libegl1`, `libgles2`, `libgl1-mesa-dri`, `libglx-mesa0`

### System Integration and Database Libraries

The application uses **X11 utilities** (`libx11-6`) and **xdg-utils** for display handling and launching external URLs or files. For local data persistence, **SQLite3** (`libsqlite3-0`, `libsqlite3-dev`) stores chat history and user settings in the local `chatmcp.db` file.

## Installing Required Packages on Ubuntu

The exact package names vary between Ubuntu 22.04 and 24.04 due to changes in the Mesa graphics stack packaging.

### Ubuntu 22.04 and Derivatives

```bash
sudo apt update
sudo apt install -y libfuse2 libgtk-3-0 \
    libegl1-mesa libgles2 libgl1-mesa-dri libglx-mesa0 \
    libx11-6 xdg-utils libsqlite3-0 libsqlite3-dev

# Optional diagnostic tools for troubleshooting GPU issues

sudo apt install -y mesa-vulkan-drivers mesa-utils

```

### Ubuntu 24.04 and Newer Versions

```bash
sudo apt update
sudo apt install -y libfuse2 libgtk-3-0 \
    libegl1 libgles2 libgl1-mesa-dri libglx-mesa0 \
    libx11-6 xdg-utils libsqlite3-0 libsqlite3-dev

# Optional diagnostic tools for troubleshooting GPU issues

sudo apt install -y mesa-vulkan-drivers mesa-utils

```

## Verifying Dependency Installation

Before running the AppImage, verify that all required libraries are present on your system:

```bash
dpkg -l libfuse2 libgtk-3-0 libegl1-mesa libgles2 libgl1-mesa-dri \
       libglx-mesa0 libx11-6 xdg-utils libsqlite3-0

```

Once dependencies are confirmed, make the AppImage executable and launch it:

```bash
chmod +x ChatMcp-linux-x86_64.AppImage
./ChatMcp-linux-x86_64.AppImage

```

## Summary

- **libfuse2** is mandatory for mounting and executing the AppImage bundle; without it, the application cannot start.
- **GTK 3** (`libgtk-3-0`) provides the native windowing framework required by Flutter's Linux embedder for UI rendering.
- **EGL/OpenGL libraries** enable hardware acceleration; note that Ubuntu 24.04 uses `libegl1` while 22.04 requires `libegl1-mesa`.
- **SQLite3** handles local persistence for chat history and application settings stored in `chatmcp.db`.
- The same package list is validated in [`.github/workflows/build.yml`](https://github.com/daodao97/chatmcp/blob/main/.github/workflows/build.yml) to ensure the CI build environment matches runtime requirements.

## Frequently Asked Questions

### Why does ChatMCP require FUSE2 instead of FUSE3?

AppImage format specifically requires **libfuse2** to mount the embedded filesystem image. While FUSE3 is available on modern systems, the AppImage runtime relies on FUSE2's specific mounting behavior to execute the bundled application as a single file without prior extraction.

### Can I run ChatMCP on Linux distributions other than Ubuntu?

Yes, provided you install equivalent packages for your distribution. The platform-specific requirements remain consistent across Linux systems: FUSE2 for AppImage support, GTK3 for the Flutter UI, Mesa/EGL libraries for graphics, and SQLite3 for the database. Package names will vary (e.g., `fuse2` on Arch Linux, `libfuse2` on Debian).

### What happens if the EGL or OpenGL libraries are missing?

Without **EGL** and **OpenGL ES** libraries, ChatMCP will either fall back to software rendering—resulting in significantly reduced UI performance—or fail to initialize the graphics context entirely, causing the application to crash on startup or display a blank window.

### Are the Vulkan drivers required for normal operation?

No, **mesa-vulkan-drivers** and **mesa-utils** are optional diagnostic tools included in the installation examples to help troubleshoot GPU compatibility issues, but they are not strictly required for ChatMCP to function normally.