Sign in Join

Live chat for Free Pascal, Lazarus, Delphi and every Pascal programmer.

Catalog · How the catalog works

Random project

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.

View on GitHub

Anyone may press Interesting, signed in or not. It helps others find this project.

Member rating

No ratings yet.

Sign in to rate this project.

README

English · Italiano · Español · Deutsch

MCP Firebird

MCP Firebird

Ask your AI assistant why a query is slow, and get an answer worth acting on.

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.6.1
  • 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)

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:

ini
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:

powershell
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:

json
{ "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

Ask What 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
"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, and how long it has been running it
"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

Sixteen tools, four 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_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). 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
Setup Prerequisites, the .env reference, --env <dir>, several databases from one build, per-client snippets, manual smoke test
Worked examples The conversations, verbatim tool output, an optimization round-trip
Tool reference Every tool, how the index advisor decides, prompts, resources, Enterprise tools
Editions & licensing What is free, what needs a licence, what Enterprise adds
Building & testing Delphi build, the 2.5→5.0 test matrix, how it uses mcp-server-delphi
Problem catalog Every problem detected, the fixture that provokes it, the milestone

Troubleshooting

Symptom Likely 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 DB Ensure firebird.host is the real host (the plan analyzer uses the configured host).
fbclient.dll not found / wrong bitness Set firebird.client_lib to a Win64 fbclient.dll; a 5.0 client works against 2.5-5.0.
stdout has non-JSON noise Logging must go to file only: keep logger.config.file=loggerpro.stdio.json.
Port 3050 already in use by another Firebird Use 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

    1. / 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.