Wire Encryption Support in MCP Firebird

June 25, 2026 · View on GitHub

📋 Overview

MCP Firebird now supports two driver options:

  1. Pure JavaScript Driver (node-firebird) - Default, simple installation, NO wire encryption support
  2. Native Driver (node-firebird-driver-native) - Optional, requires compilation, FULL wire encryption support

⚠️ Default Driver Limitation

The default node-firebird library does NOT support Firebird 3.0+ wire encryption protocol.

This means that by default, mcp-firebird CANNOT connect to Firebird 3.0+ servers that have wire encryption enabled.

The Problem

When connecting to a Firebird 3.0+ server with wire encryption enabled, you will see this error:

Error connecting to database: Incompatible wire encryption levels requested on client and server

Why the --wire-crypt Parameter Doesn't Work

The --wire-crypt parameter was added to mcp-firebird based on a misunderstanding of the node-firebird library's capabilities.

The truth is:

  • node-firebird does NOT implement the Firebird 3.0+ wire encryption protocol
  • The library can ONLY connect to servers with wire encryption disabled
  • No client-side parameter can change this limitation

If you need wire encryption support, use the --use-native-driver flag:

npx -y mcp-firebird --use-native-driver \
  --database=/path/to/database.fdb \
  --host=localhost \
  --port=3050 \
  --user=SYSDBA \
  --password=masterkey

⚠️ IMPORTANT: Wire Encryption Configuration

Wire encryption CANNOT be configured from the client side. According to Firebird documentation, WireCrypt is a server-side parameter that must be configured in the server's firebird.conf file.

The --wire-crypt parameter in MCP Firebird does NOT work and will be ignored with a warning message.

To use wire encryption:

  1. Configure WireCrypt in the server's firebird.conf: 
    WireCrypt = Required  # or Enabled
  2. Restart the Firebird server
  3. Use the native driver (which supports the wire encryption protocol)

Requirements for Native Driver

  1. Install build tools (one-time setup):

    Windows:

    Linux (Ubuntu/Debian):

    sudo apt-get update
sudo apt-get install -y build-essential python3 firebird-dev

    Linux (CentOS/RHEL/Fedora):

    sudo yum groupinstall "Development Tools"
sudo yum install python3 firebird-devel

    macOS:

    xcode-select --install
brew install firebird

  2. Install Firebird client library:

    Windows:

    Linux (Ubuntu/Debian):

    sudo apt-get install firebird3.0-client
# or for Firebird 4.0+
sudo apt-get install firebird4.0-client

    Linux (CentOS/RHEL):

    sudo yum install firebird-classic

    macOS:

    brew install firebird

  3. Install the native driver:

    npm install -g 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

For detailed installation instructions, see Advanced Installation Guide.

Benefits of Native Driver

  • ✅ Wire encryption support (when configured on server)
  • ✅ Better performance (uses native fbclient library)
  • ✅ All Firebird features supported
  • ❌ More complex installation (requires compilation)

Solution 2: Disable Wire Encryption on Server (Simpler)

If you don't need wire encryption, you can disable it on the Firebird server by modifying the firebird.conf file.

For Firebird 3.0

Add or modify these lines in firebird.conf:

AuthServer = Srp, Legacy_Auth
WireCrypt = Disabled
UserManager = Legacy_UserManager

For Firebird 4.0

Add or modify these lines in firebird.conf:

AuthServer = Srp256, Srp, Legacy_Auth
WireCrypt = Disabled
UserManager = Legacy_UserManager

For Firebird 5.0 (Docker)

If using Docker, set environment variables in your docker-compose.yml:

services:
  firebird:
    image: firebirdsql/firebird:5
    environment:
      FIREBIRD_ROOT_PASSWORD: masterkey
      FIREBIRD_CONF_WireCrypt: Disabled
      FIREBIRD_CONF_AuthServer: Srp256, Srp

Credit: Solution for Firebird 5.0 Docker provided by @esciara

What If I Can't Change Server Configuration?

If you cannot modify the Firebird server configuration (e.g., company-managed server), you have these options:

Option 1: Request Server Configuration Change

Contact your database administrator and request that they disable wire encryption for your connection. Explain that:

  • The Node.js Firebird client library doesn't support the new wire protocol
  • Wire encryption can be disabled for specific connections while keeping it enabled for others
  • This is a known limitation of the node-firebird library

Option 2: Use a Different Client Library

Consider using a different Firebird client that supports wire encryption:

Python Alternative:

  • Library: firebirdsql or fdb
  • Both support Firebird 3.0+ wire encryption
  • You could create a simple REST API wrapper around these libraries

Example Python wrapper:

import firebirdsql
from flask import Flask, jsonify, request

app = Flask(__name__)

@app.route('/query', methods=['POST'])
def execute_query():
    with firebirdsql.connect(
        host=request.json['host'],
        port=request.json['port'],
        database=request.json['database'],
        user=request.json['user'],
        password=request.json['password'],
        charset='UTF8'
    ) as conn:
        cursor = conn.cursor()
        cursor.execute(request.json['sql'])
        return jsonify(cursor.fetchall())

if __name__ == '__main__':
    app.run(port=5000)

Then configure mcp-firebird to use this wrapper (requires custom development).

Option 3: Use Firebird 2.5

If possible, use a Firebird 2.5 server which doesn't have wire encryption enabled by default.

Option 4: Wait for Library Update

Monitor the node-firebird repository for updates that add wire encryption support:

Note: As of October 2025, there is no active development on wire encryption support.

Alternative Libraries to Consider

If wire encryption support is critical for your use case, consider these alternatives:

  1. node-firebird-native-api (if it exists and supports wire encryption)
  2. Create a bridge using Python's firebirdsql library
  3. Use Firebird's REST API (if available in your version)
  4. Contribute to node-firebird to add wire encryption support

Authentication Issues (Firebird 5.0)

If you see this error:

Error connecting to database: Error occurred during login, please check server firebird.log for details

And the Firebird logs show:

Authentication error
No matching plugins on server

Solution: Add AuthServer configuration to your Firebird server:

AuthServer = Srp256, Srp

Or in Docker:

FIREBIRD_CONF_AuthServer: Srp256, Srp

Summary

ScenarioSolution
You control the serverDisable WireCrypt in firebird.conf
Docker deploymentSet FIREBIRD_CONF_WireCrypt: Disabled
Company-managed serverRequest admin to disable wire encryption
Cannot change serverUse alternative client library or Python wrapper
Authentication error (FB5)Add AuthServer: Srp256, Srp to server config

References

Acknowledgments