mcp-firebird

A Model Context Protocol server for Firebird 2.5 – 5.0, written in Delphi with the official `fbclient` driver. It lets an AI assistant document schemas, analyze query plans, advise on indexes (which to add and which to drop), audit schema health, and drive goal-based optimization. Read-only by default.

文件

English · Italiano · Español · Deutsch

MCP Firebird

License: PolyForm Internal Use 1.0.0 MCP protocol 2025-03-26 powered by mcp-server-delphi CI

MCP Firebird

The Firebird MCP server built for DBAs: query tuning, index advice and database health. Ask your AI assistant why a query is slow, and get an answer worth acting on.

Most database MCP servers are a pipe. The assistant sends SQL, rows come back, and that is the whole job. MCP Firebird is designed for optimization and DBA work. Reading rows is a side feature (fb_query); the point is the work a DBA does: reading access plans, deciding which index to create and which to drop, auditing a schema, and finding what is slowing the database down.

A Model Context Protocol server for Firebird 2.5 to 5.0. Point it at a database and your assistant can read the real access plans, tell you which index is missing and which four are dead weight, audit a table's health, and find the transaction that has been holding garbage collection back since Tuesday.

The answers come out of your database, not out of an article: the server asks Firebird for the plan (SET PLANONLY), reads the monitoring tables (MON$), and counts how many distinct values a column really holds before claiming an index on it would pay off. Every answer arrives as Finding (what is wrong), SQL (the statement that fixes it) and Verify (how to check it worked). Nothing is written to your database: the server attaches read-only, and the SQL it hands you is yours to run, if and when you decide to.

  • Transport: stdio (JSON-RPC 2.0, MCP 2025-03-26) · Server identity: mcp-firebird v0.7.0
  • Engines: Firebird 2.5, 3.0, 4.0, 5.0 — capability-detected at runtime
  • Free on your own databases, at any scale, no key and no expiry. A licence is needed only to pass the software on to somebody else (details)

Built for the DBA, not for data access

A SQL prompt gives an assistant rows in and rows out. MCP Firebird is organised around the DBA's questions instead, and checks each answer against your database before giving it:

  • Why is this slow? The real plan, the NATURAL scans and external sorts in it, and what the query cost when executed once: records read against rows returned.
  • Which index? The cheapest fix that explains the plan: refresh statistics, reactivate an index, or create one. When the scan is the right plan the answer is "no index", with the numbers.
  • What is dead weight? Duplicate, redundant, inactive and low-selectivity indexes, with the DROP INDEX and how to verify it.
  • Is the database healthy? Stale statistics, missing keys, the transaction pinning garbage collection, who is connected and what they are running, who can read what, a backup proved by restoring it.
  • Did the fix work? Every answer is a Finding, the SQL, and a Verify step, and the optimization_goal loop stops when the measurement says the goal is met.

Quickstart

Five minutes, four steps. Windows x64.

1. Get the server. Download the latest release and unzip it, say into C:\Tools\MCPFirebird. Building from source instead: Building & testing.

2. Tell it which database. Copy .env.example next to the exe as .env and fill in four lines:

firebird.database=C:\data\MYAPP.FDB
firebird.user=SYSDBA
firebird.password=masterkey
firebird.client_lib=C:\Program Files\Firebird\Firebird_5_0\fbclient.dll

The zip deliberately ships no fbclient.dll: the right one is your own server's client library.

3. Register it with your AI agent. It is a stdio server — the agent starts the exe itself, so the whole installation is one command. Claude Code:

claude mcp add firebird -- "C:\Tools\MCPFirebird\MCPFirebird.exe"

Claude Desktop (%APPDATA%\Claude\claude_desktop_config.json), Cursor (.cursor/mcp.json), VS Code (.vscode/mcp.json) all take the same shape:

{ "mcpServers": { "firebird": { "command": "C:\\Tools\\MCPFirebird\\MCPFirebird.exe" } } }

Gemini CLI and OpenCode differ slightly — snippets for every client are in Setup.

4. Ask it something.

You: What Firebird version am I connected to, and which tables are in the database?

You: This query is slow, why? SELECT * FROM CUSTOMERS WHERE CITY = 'Rome'

You: Suggest an index that fixes it.

That is the whole setup. If the client lists the server but shows no tools, see Troubleshooting, at the bottom of this page.


What you can ask it

AskWhat happens
"Document the CUSTOMERS table"Markdown docs: columns, PK, indexes, triggers. Leave the table out and you get the whole database, procedures and packages included
"Why is this query slow?"The access plan, the NATURAL scans and external sorts in it, the engine's explained plan on 3.0+, and what the query really cost when executed once
"Suggest an index"The cheapest remedy that explains the plan — refresh stale statistics, wake an inactive index, or create one — and "no index, the scan is right here" with the numbers, when that is the answer
"Which indexes can I drop?"Duplicates, redundant prefixes, inactive and low-selectivity indexes, with the DROP INDEX and a verify step
"Audit this table"Missing primary key, over-indexing, stale statistics
"What is really in these columns?"fb_column_stats: rows, NULLs, distinct values and selectivity from one scan, beside what the index believes. Stale figures are marked
"Show me the source of this procedure / trigger"fb_describe_object: the PSQL as the engine stored it, with its signature or the event it fires on
"Keep optimizing until this query stops scanning NATURAL"The goal loop: it changes, re-measures on the database, and stops when the measurement says the goal is met — not when the assistant thinks so
"It crawls every afternoon and nobody changed anything"Classifies the symptom before touching a tool, then samples MON$ across a window to show what accumulates
"Who is connected, and what are they running?"Every attachment with its user, address and process, the statement it is running now, how long it has been running it, and (4.0+) whether the connection is encrypted
"Show me the rows that are actually in there"fb_query runs the SELECT and returns the rows, capped so an answer stays an answer. Nothing else is accepted: not an UPDATE, not a DELETE, not a DDL
"Our app connects as SYSDBA. What should it use instead?"app_user_plan asks what the application actually does — a handful of questions, each of which changes the statements — then fb_suggest_grants writes them from the catalogue: the account, a role, the grants, and the role activated the way your engine version needs
"Who can read this table?"Every grant recorded in the database, and the three that are usually mistakes: PUBLIC, WITH GRANT OPTION, and roles nobody is a member of
"Back the database up"Runs gbak in the background and restores what it wrote into a scratch database, so the answer is "this backup restores", not "a file exists"

Every analysis also closes with what it does not rule out: a plan cannot see contention, and a snapshot cannot see accumulation.

→ Worked examples, verbatim tool output, a full round-trip on employee.fdb


The tools

Eighteen tools, seven prompts, one resource. Full reference — arguments, what each one decides, the raw tools/call shapes — in docs/tools.md.

fb_info · fb_list_tables · fb_generate_documentation · fb_describe_object · fb_column_stats · fb_query · fb_analyze_query · fb_suggest_indexes · fb_suggest_index_drops · fb_audit_table · fb_audit_security · fb_suggest_grants · fb_evaluate_goal · fb_monitor_transactions · fb_sample_activity · fb_monitor_attachments · fb_backup_start · fb_backup_status

fb_backup_start returns before the backup does — poll fb_backup_status. It needs firebird.backup_dir set in the .env, gbak.exe beside your fbclient.dll, and room on that disk for a second copy of the database while the verification restore runs.

Prompts: optimization_goal (iterate until met) · health_check · classify_problem · app_user_plan (work out what an application account should be allowed to do, and produce the SQL) · migration_planning (move to another Firebird version, working from what the database contains) · schema_design_review · security_audit. Resource: firebird://schema.

Nine further tools appear in tools/list and belong to the Enterprise edition: your assistant can see them and say what it would do with them.


Editions

Using it on your own databases is free, and stays free. No trial, no expiry, no licence key, no seat count. Consultants: it is your tool, use it on your clients' databases and charge for your time. The one thing that needs a licence is letting a copy out of your hands — redistributing it, embedding it in a product you sell, or offering it as a service.

A separate paid Enterprise edition picks up where an SQL connection ends: firebird.conf, the machine's RAM and CPUs, firebird.log, the Trace API, the physical storage report. You want it when the schema is in order and the database is still slow.

→ Editions, licensing, and the worked cases · d.teti@bittime.it


Documentation

SetupPrerequisites, the .env reference, --env <dir>, several databases from one build, per-client snippets, manual smoke test
Worked examplesThe conversations, verbatim tool output, an optimization round-trip
Tool referenceEvery tool, how the index advisor decides, prompts, resources, Enterprise tools
Editions & licensingWhat is free, what needs a licence, what Enterprise adds
Building & testingDelphi build, the 2.5→5.0 test matrix, how it uses mcp-server-delphi
Problem catalogEvery problem detected, the fixture that provokes it, the milestone

Troubleshooting

SymptomLikely cause / fix
Client shows the server but no tools.env missing or DB unreachable: the server starts but tools fail on connect. Test with the manual smoke test.
Your user name and password are not defined (SQLSTATE 28000)Wrong credentials, or a Firebird zip-kit that ships without a usable SYSDBA (see Building & testing).
Analysis tools return empty / no NATURAL scan on a remote DBEnsure firebird.host is the real host (the plan analyzer uses the configured host).
fbclient.dll not found / wrong bitnessSet firebird.client_lib to a Win64 fbclient.dll; a 5.0 client works against 2.5-5.0.
stdout has non-JSON noiseLogging must go to file only: keep logger.config.file=loggerpro.stdio.json.
Port 3050 already in use by another FirebirdUse a distinct port (the test harness puts FB 2.5 on 3070 for this reason).

Safety & compatibility

  • Read-only, and not on the honour system. The server opens its transactions read-only, so an INSERT, UPDATE, DELETE or DDL is refused by Firebird, not by a check of ours that could be wrong about what a statement does. It matters because four tools execute SQL that arrives as text from the caller — fb_query returns its rows, fb_analyze_query measures the SELECT it analyzes, fb_suggest_indexes measures the one it advises on, and fb_evaluate_goal times one. All four also refuse anything that is not a plain SELECT before running it, and refuse to execute a statement whose parameters nobody bound; the read-only transaction is what holds if a refusal is ever wrong.

    That order matters, and it is the opposite of a keyword blocklist. A list of forbidden words — no INSERT, no DROP — is a guess about text: it does not know that EXECUTE PROCEDURE can write, that a statement can be assembled to spell nothing on the list, or that the next release adds a keyword nobody added to the list. The read-only TPB is not a guess. Whatever text arrives, whatever it means, the transaction it runs in cannot write, and the engine is the one saying so. The SQL an advisory hands you is yours to run, when and if you decide to. Tools that apply a change themselves are planned, and when they arrive they will be off unless you turn them on.

  • Cross-version. Capability detection adapts feature use (MON$ tables, explained plans, BOOLEAN, INT128, timezones, parallel workers) to the connected engine; validated on FB 2.5 / 3.0 / 4.0 / 5.0.

  • Single configured database per server instance (run multiple instances for multiple DBs).


License

From v0.2.0, licensed under the PolyForm Internal Use License 1.0.0: free on your own databases, at any scale, and a licence is needed only to pass the software on to somebody else. v0.1.0 and earlier were released under Apache-2.0, and stay that way for everyone who received them. See Editions & licensing and NOTICE.

Built with mcp-server-delphi, which in turn stands on DelphiMVCFramework. This server is a complete, real-world example of what you can build with them: if you are writing your own MCP server in Delphi, start there.