Firebird Model Context Protocol (MCP) Server

Common errors

• Container startup failures: Ensure the DATABASE environment variable is properly set

  cause The `DATABASE` environment variable (or equivalent CLI argument) is missing or points to an invalid path for the Firebird database file.
  fix Set the `DATABASE` environment variable or `--database` CLI argument to the correct absolute path of your Firebird `.fdb` database file. For Docker, ensure the path reflects the location inside the container's filesystem after volume mounting.

• ERROR: Unable to connect to Firebird database. Check host, port, user, and password.

  cause Incorrect network configuration, invalid credentials, or the Firebird database server is not running or accessible.
  fix Verify that the Firebird database server is active and listening on the specified host and port. Double-check the `FIREBIRD_HOST`, `FIREBIRD_PORT`, `FIREBIRD_USER`, and `FIREBIRD_PASSWORD` environment variables or their CLI counterparts for accuracy. Check firewall rules.

• Error: EACCES: permission denied, access '/firebird/data/your_db.fdb'

  cause The user account running the mcp-firebird server lacks sufficient read/write permissions for the Firebird database file or its directory.
  fix Adjust file system permissions for the Firebird database file and its parent directory to grant read and write access to the user account or group under which the mcp-firebird process is running.

Warnings

• breaking The Model Context Protocol (MCP) itself has undergone significant breaking changes, notably with the migration from MCP v1 to v2. Users should ensure their mcp-firebird server and any client applications are compatible with the specific MCP protocol version being used to avoid communication errors or unexpected behavior.
  Fix: Refer to the official MCP documentation and mcp-firebird release notes for compatibility details. Ensure that both the server and client adhere to the same MCP protocol version. Older MCP servers using `FastMCP` have been replaced by `McpServer` in newer SDKs.
• gotcha Incorrect or insufficient Firebird database connection parameters (host, port, database path, user, password) will prevent the server from connecting to the database. These are critical for server startup and functionality.
  Fix: Verify all connection parameters are correct. Ensure the Firebird database server is running and accessible from the machine hosting the mcp-firebird server. Double-check environment variables or CLI arguments for typos.
• gotcha File system permissions issues on the Firebird database file (`.fdb`) or data volumes, as well as initialization scripts, can lead to container startup failures or database access errors.
  Fix: Ensure that the user running the mcp-firebird server (or the Docker container user) has appropriate read/write permissions to the Firebird database file and any associated data directories. Check permissions on `init.sql` and `test_db.sql` if used for database initialization.
• gotcha When running mcp-firebird within a Docker container, ensure that the `DATABASE` environment variable is correctly set to the path *inside the container* where the database file is mounted. Improper volume mounts or incorrect paths will lead to connection failures.
  Fix: Review your Dockerfile and Docker Compose configuration to ensure the Firebird database file is correctly mounted as a volume and the `DATABASE` environment variable points to the correct location within the container.

Install

• npm install mcp-firebird npm
• yarn add mcp-firebird yarn
• pnpm add mcp-firebird pnpm

Imports

• mcp-firebird

  npx mcp-firebird

  This package is primarily designed to be run as a command-line server via `npx` rather than being imported as a library into other Node.js projects. Its core functionality is exposed through the CLI and the Model Context Protocol itself. Although it ships TypeScript types, these are generally for internal server components or configuration objects, not for external programmatic library usage.
• MCP Server Configuration
  wrong:

  import { configure } from 'mcp-firebird'

  correct:

  Via environment variables or command-line arguments

  Configuration for the mcp-firebird server is typically done through environment variables (e.g., FIREBIRD_HOST, FIREBIRD_DATABASE) or by passing arguments directly to the `npx mcp-firebird` command, as opposed to a programmatic configuration API.

Quickstart

Demonstrates how to run the mcp-firebird server using `npx`, configuring it via both command-line arguments and environment variables for connecting to a Firebird database and enabling SSE transport.

import { spawn } from 'child_process';

const databasePath = process.env.FIREBIRD_DATABASE_PATH ?? '/firebird/data/test_db.fdb';
const user = process.env.FIREBIRD_USER ?? 'SYSDBA';
const password = process.env.FIREBIRD_PASSWORD ?? 'masterkey';
const host = process.env.FIREBIRD_HOST ?? 'localhost';
const port = process.env.FIREBIRD_PORT ?? '3050';

// Example of running mcp-firebird via npx with environment variables and CLI arguments
const mcpFirebirdProcess = spawn('npx', [
  'mcp-firebird',
  '--database', databasePath,
  '--user', user,
  '--password', password,
  '--host', host,
  '--port', port,
  '--transport', 'sse', // Use Server-Sent Events transport
  '--sse-port', '3003' // Specify SSE port
], {
  stdio: 'inherit',
  env: { ...process.env, 
    LOG_LEVEL: 'debug' // Example of an additional environment variable
  }
});

mcpFirebirdProcess.on('error', (err) => {
  console.error('Failed to start mcp-firebird process:', err);
});

mcpFirebirdProcess.on('exit', (code) => {
  console.log(`mcp-firebird process exited with code ${code}`);
});

console.log('MCP Firebird server started. Connect your AI client (e.g., Claude Desktop) to this server.');
console.log(`Database: ${databasePath}, User: ${user}, Host: ${host}, Port: ${port}`);
console.log('SSE Transport active on port 3003.');