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

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 and the CI configuration in .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

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

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:

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:

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

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