Native Driver Installation Guide

June 25, 2026 · View on GitHub

Complete guide for installing node-firebird-driver-native on different operating systems.

📋 Table of Contents

Overview
Windows Installation
Linux Installation
macOS Installation
Verification
Troubleshooting

Overview

The native driver (node-firebird-driver-native) requires:

Build tools (to compile native code)
Firebird client library (fbclient)
Node.js (v14 or higher)

Benefits:

✅ Wire encryption support (when configured on server)
✅ Proactive Events Support (POST_EVENT triggers for real-time notifications)
✅ Better performance (2-3x faster)
✅ Full Firebird feature support

Drawbacks:

❌ Complex installation
❌ Requires admin/sudo privileges
❌ Larger installation size (~7 GB on Windows)

⚠️ CRITICAL: NPX Does NOT Work with Native Driver

npx -y mcp-firebird CANNOT use the native driver, even if node-firebird-driver-native is installed globally.

Why? When npx runs a package, it downloads it to a temporary cache folder (C:\Users\...\npm-cache\_npx\...). Node.js module resolution (require() and import()) can only find modules in:

The same node_modules folder as the running package
Parent directories of the running package

Global modules are installed in a completely different location (C:\Users\...\AppData\Roaming\npm\node_modules), so they are invisible to packages running from npx's temporary cache.

The ONLY solution for wire encryption support:

✅ Global Installation (Required for Native Driver)

# Step 1: Install mcp-firebird globally
npm install -g mcp-firebird

# Step 2: Install native driver globally
npm install -g node-firebird-driver-native

# Step 3: Verify both are in the same location
npm list -g mcp-firebird
npm list -g node-firebird-driver-native

# Step 4: Run directly (WITHOUT npx)
mcp-firebird --use-native-driver --database "path/to/database.fdb" --user SYSDBA --password masterkey

Alternative: Automated Installation Script (Windows)

# Download and run the installation script
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/PuroDelphi/mcpFirebird/main/install-with-native-driver.ps1" -OutFile "install.ps1"
.\install.ps1

Windows Installation

Prerequisites

Windows 10/11 (64-bit)
Administrator privileges
~10 GB free disk space

Step 1: Install Visual Studio Build Tools

Required for compiling native Node.js modules.

Download Visual Studio Build Tools:
- URL: https://visualstudio.microsoft.com/downloads/
- Scroll down to "Tools for Visual Studio"
- Download "Build Tools for Visual Studio 2022"
Run the installer:
- Launch vs_BuildTools.exe
- Select "Desktop development with C++"
- Click "Install"
- Size: ~7 GB
- Time: 20-40 minutes (depending on internet speed)

Verify installation:

# Open PowerShell as Administrator
npm config get msvs_version
# Should show: 2022 (or similar)

Step 2: Install Firebird Client

Download Firebird:
- URL: https://firebirdsql.org/en/firebird-5-0/
- Select "Windows 64-bit"
- Download the installer (e.g., Firebird-5.0.0.1306-0-x64.exe)
Run installer:
- Launch the downloaded .exe file
- Select "Client installation only" (unless you need the server)
- Choose installation directory (default: C:\Program Files\Firebird\Firebird_5_0)
- Complete installation

Verify installation:

# Check if fbclient.dll exists
dir "C:\Program Files\Firebird\Firebird_5_0\fbclient.dll"

⚠️ CRITICAL: Verify 64-bit DLL:

Node.js is typically 64-bit, so you MUST use a 64-bit fbclient.dll. Using a 32-bit DLL will cause the error:
```
Cannot load Firebird client library: 'fbclient.dll'
```
Verify Node.js architecture:
```
node -p "process.arch"
# Should output: x64
```
Verify fbclient.dll architecture:
```
# Using Git Bash or WSL
file "C:/Program Files/Firebird/Firebird_5_0/fbclient.dll"
# Should output: PE32+ executable (DLL) ... x86-64
# NOT: PE32 executable (DLL) ... Intel 80386 (32-bit)
```
If you have a 32-bit DLL:
- Download the 64-bit version of Firebird from https://firebirdsql.org/
- Look for "Windows 64-bit" or "x64" in the download name
- Uninstall the 32-bit version first
- Install the 64-bit version

Add to PATH (if not already added):

# Add Firebird bin directory to PATH
$env:Path += ";C:\Program Files\Firebird\Firebird_5_0"

# Make it permanent (run as Administrator)
[Environment]::SetEnvironmentVariable(
    "Path",
    [Environment]::GetEnvironmentVariable("Path", "Machine") + ";C:\Program Files\Firebird\Firebird_5_0",
    "Machine"
)

Step 3: Install Native Driver

# Install globally
npm install -g node-firebird-driver-native

# Or install locally in your project
npm install node-firebird-driver-native

Expected output:

> node-firebird-native-api@3.1.2 install
> node-gyp rebuild

  CXX(target) Release/obj.target/addon/src/...
  SOLINK_MODULE(target) Release/addon.node
+ node-firebird-driver-native@3.2.2

Step 4: Test Installation

# Test if the driver can be loaded
node -e "try { require('node-firebird-driver-native'); console.log('✅ Native driver installed successfully'); } catch(e) { console.log('❌ Error:', e.message); }"

# Update package list
sudo apt-get update

# Install build essentials
sudo apt-get install -y build-essential python3 python3-pip

# Verify installation
gcc --version
g++ --version
python3 --version

Step 2: Install Firebird Client

# For Firebird 3.0
sudo apt-get install -y firebird3.0-client firebird-dev

# For Firebird 4.0
sudo apt-get install -y firebird4.0-client firebird-dev

# Verify installation
dpkg -l | grep firebird

Step 3: Install Native Driver

# Install globally
sudo npm install -g node-firebird-driver-native

# Or install locally
npm install node-firebird-driver-native

CentOS/RHEL/Fedora

Step 1: Install Build Tools

# Install Development Tools group
sudo yum groupinstall "Development Tools"

# Install Python 3
sudo yum install python3

# Verify installation
gcc --version
python3 --version

Step 2: Install Firebird Client

# Install Firebird
sudo yum install firebird-classic firebird-devel

# Or download from firebirdsql.org
wget https://github.com/FirebirdSQL/firebird/releases/download/v4.0.0/Firebird-4.0.0.2496-0.amd64.tar.gz
tar -xzf Firebird-4.0.0.2496-0.amd64.tar.gz
cd Firebird-4.0.0.2496-0.amd64
sudo ./install.sh

Step 3: Install Native Driver

# Install globally
sudo npm install -g node-firebird-driver-native

# Or install locally
npm install node-firebird-driver-native

Arch Linux

# Install build tools
sudo pacman -S base-devel python

# Install Firebird (from AUR)
yay -S firebird

# Install native driver
sudo npm install -g node-firebird-driver-native

macOS Installation

Step 1: Install Xcode Command Line Tools

# Install Xcode Command Line Tools
xcode-select --install

# Verify installation
xcode-select -p
# Should output: /Library/Developer/CommandLineTools

Step 2: Install Homebrew (if not installed)

# Install Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Verify installation
brew --version

Step 3: Install Firebird

# Install Firebird via Homebrew
brew install firebird

# Verify installation
brew list firebird

Step 4: Install Native Driver

# Install globally
sudo npm install -g node-firebird-driver-native

# Or install locally
npm install node-firebird-driver-native

Verification

After installation, verify everything works:

# Test 1: Check if module can be loaded
node -e "try { require('node-firebird-driver-native'); console.log('✅ Module loaded'); } catch(e) { console.log('❌ Error:', e.message); }"

# Test 2: Use with MCP Firebird
npx mcp-firebird --use-native-driver \
  --database=/path/to/test.fdb \
  --host=localhost \
  --user=SYSDBA \
  --password=masterkey

Expected output:

Using native Firebird driver (supports wire encryption)
Conectando con node-firebird-driver-native (Native Client)...
Conexión exitosa con node-firebird-driver-native

Troubleshooting

Error: "node-gyp rebuild failed"

Cause: Build tools not installed or not found.

Solution:

Windows: Install Visual Studio Build Tools (see Step 1)
Linux: sudo apt-get install build-essential python3
macOS: xcode-select --install

Error: "Cannot find module 'node-firebird-driver-native'"

Cause: Module not installed or not in the correct location.

Solution:

# Check if installed globally
npm list -g node-firebird-driver-native

# If not found, install it
npm install -g node-firebird-driver-native

Error: "fbclient library not found" (Linux)

Cause: Firebird client library not installed or not in library path.

Solution:

# Install Firebird client
sudo apt-get install firebird3.0-client firebird-dev

# Update library cache
sudo ldconfig

# Verify fbclient.so exists
find /usr -name "libfbclient.so*"

Error: "gyp ERR! find VS" (Windows)

Cause: Visual Studio Build Tools not found.

Solution:

Install Visual Studio Build Tools 2022
Make sure "Desktop development with C++" is selected
Restart your terminal/PowerShell
Try again

Error: "Permission denied" (Linux/macOS)

Cause: Insufficient permissions to install globally.

Solution:

# Use sudo for global installation
sudo npm install -g node-firebird-driver-native

# Or install locally (no sudo needed)
npm install node-firebird-driver-native

Next Steps

Once the native driver is installed:

Configure wire encryption on your Firebird server (see Wire Encryption Guide)
Use the native driver with --use-native-driver flag
Test your connection with a simple query

Related Documentation: