firebird-mcp-server

MCP server (stdio) that gives AI harnesses read/write access to Firebird databases: saved connection profiles, schema discovery, paginated table reads, and raw SQL.

All tools return JSON text. Read queries paginate with 50 rows by default (max 500).

Install

npm install -g firebird-mcp-server
# or
bun install -g firebird-mcp-server
# or
pnpm install -g firebird-mcp-server

Then start the server with:

firebird-mcp mcp

Stack

• Bun — package manager / runtime
• TypeScript + tsdown — build (dist/index.mjs)
• @modelcontextprotocol/sdk — MCP
• node-firebird — Firebird wire protocol (pure JS)

Development

bun install
bun run build

Dev (no bundle):

bun run dev

Tests:

bun test

Connection profiles

Stored by default at:

~/.config/firebird-mcp/connections.json

Env vars:

export FIREBIRD_MCP_CONFIG=/path/to/connections.json   # config file path
export FIREBIRD_MCP_READONLY=1                         # block all writes (any profile)
export FIREBIRD_MCP_ATTACH_TIMEOUT_MS=10000            # connect timeout (default 10s)

Example file:

{
  "version": 1,
  "active": "local",
  "connections": {
    "local": {
      "host": "localhost",
      "port": 3050,
      "database": "/data/app.fdb",
      "user": "SYSDBA",
      "password": "masterkey",
      "charset": "UTF8",
      "readonly": false
    }
  }
}

Per-profile "readonly": true makes raw_query reject INSERT/UPDATE/DELETE/DDL on that profile.

Passwords are stored in plaintext in that file — the server writes it with mode 0600; keep it that way.

Docs for the AI (built-in)

The server teaches the harness how to use it without external docs:

| Primitive | What | When the model sees it | |-----------|------|------------------------| | instructions | Short workflow + rules | On MCP connect (system prompt) | | Resource firebird://docs/usage | Full markdown guide (tools, pagination, Firebird notes) | When the host loads/lists resources | | Tool descriptions | Per-tool contracts | Always in the tool list |

Source: src/docs.ts.

Tools

| Tool | Purpose | |------|---------| | list_connections | List saved profiles + active | | save_connection | Create/update a profile (optional setActive) | | delete_connection | Remove a profile | | use_connection | Set active profile (persisted) | | get_active_connection | Show active profile (no password) | | test_connection | Ping DB / engine version | | list_tables | Tables (optional views / system) | | describe_table | Columns + indexes + constraints + triggers | | list_indexes | Indexes (optional table filter) | | list_constraints | PK/FK/UNIQUE/CHECK (optional table) | | list_triggers | Triggers (optional table filter) | | list_procedures | Stored procedures + parameters | | list_functions | UDFs / functions + arguments | | list_generators | Generators/sequences (optional current values) | | get_table_data | SELECT * with pagination | | get_column_metadata | Full metadata for one column (type, default, PK, FKs, indexes) | | raw_query | Arbitrary SQL; SELECT auto-paginated; writes blocked on readonly profiles | | execute_transaction | Multiple statements in one atomic transaction — all commit or all roll back |

Monitoring

No dedicated tools needed — Firebird exposes live monitoring as regular tables, queryable via raw_query: MON$DATABASE, MON$ATTACHMENTS, MON$TRANSACTIONS, MON$STATEMENTS, MON$IO_STATS, MON$RECORD_STATS. The built-in usage guide (firebird://docs/usage) documents them with example queries so the AI knows they exist.

Pagination shape

{
  "rows": [ /* ... */ ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "rowCount": 50,
    "hasMore": true,
    "nextOffset": 50
  }
}

raw_query wraps plain SELECT as:

SELECT FIRST {limit+1} SKIP {offset} * FROM ( /* your sql */ )

CTEs (WITH ...) get ROWS {offset+1} TO {offset+limit+1} appended instead (Firebird rejects WITH in derived tables). If the SQL already contains FIRST / SKIP / ROWS / OFFSET outside literals/comments, it runs as-is.

Writes return { "kind": "write", "rows": [...] } — rows holds RETURNING output; the driver reports no affected-row count.

Claude / Cursor / harness config

Install the package globally first (npm/bun/pnpm i -g firebird-mcp-server), then:

{
  "mcpServers": {
    "firebird": {
      "command": "bunx",
      "args": ["firebird-mcp-server", "mcp"]
    }
  }
}

Or pointing straight at the global binary:

{
  "mcpServers": {
    "firebird": {
      "command": "firebird-mcp",
      "args": ["mcp"]
    }
  }
}

From a local checkout (no build needed):

{
  "mcpServers": {
    "firebird": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/firebird-mcp/src/index.ts", "mcp"]
    }
  }
}

Typical harness flow

1. save_connection → test_connection
2. list_tables → describe_table
3. get_table_data or raw_query with limit / offset
4. Writes via raw_query (single statement) or execute_transaction (atomic batch) — blocked on readonly profiles

License

MIT