Metadata-Version: 2.4
Name: firebird-sql-mcp
Version: 0.1.0a3
Summary: Read-only MCP server for Firebird databases
Project-URL: Repository, https://github.com/dimitar-grigorov/firebird-sql-mcp
Author: Dimitar Grigorov
License-Expression: AGPL-3.0-only
License-File: LICENSE
Keywords: database,firebird,mcp,read-only,sql
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Requires-Python: >=3.11
Requires-Dist: fastmcp>=3.0
Requires-Dist: firebird-driver>=2.0
Requires-Dist: keyring>=25
Requires-Dist: platformdirs>=4
Requires-Dist: sqlparse>=0.5
Requires-Dist: tomlkit>=0.12
Description-Content-Type: text/markdown

# firebird-sql-mcp

Read-only [MCP](https://modelcontextprotocol.io) server for [Firebird](https://firebirdsql.org) databases.
Gives AI assistants (Claude Desktop, Claude Code, Cursor, ...) safe access to a database:
browse the schema, run SELECT queries, never write anything. **Status: alpha.**

## Tools

| Tool | What it does |
|------|--------------|
| `list_profiles` | Configured connection profiles (never includes secrets) |
| `list_tables` | User tables and views, filter by kind or name |
| `describe_table` | Columns and types, primary key, foreign keys, indexes |
| `run_query` | Run one SELECT/WITH statement, capped by row count and a 1 MiB budget |
| `explain_query` | The engine's execution plan, without executing the query |

## How read-only is enforced

Not by SQL string filtering alone. Every query runs inside a Firebird read-only
transaction, so the engine itself rejects writes even if a statement slips past
the SQL gate; transactions are always rolled back, never committed. A statement
timeout and response caps limit runaway queries, and every query is written to
a JSONL audit log. Passwords live in the OS keyring, never in files or logs.

## Requirements

- Python 3.11+ and a Firebird client library (`fbclient.dll` / `libfbclient.so`);
  set `FBMCP_FB_CLIENT_LIBRARY` if it is not on the default search path.
- Firebird server 3.0+ (developed against 5.0); embedded databases work too.

## Install and set up

Claude Code, as a plugin (needs [uv](https://docs.astral.sh/uv/); details in
[plugin/README.md](plugin/README.md)):

```
/plugin marketplace add dimitar-grigorov/firebird-sql-mcp
/plugin install firebird-sql-mcp
```

Everywhere else, install the package (`pip`, `pipx` or `uv tool`):

```
pip install firebird-sql-mcp
```

Then add a profile - one command creates the config, stores the password in
the OS keyring and tests the connection. Omit `--host` for an embedded local
file. With the plugin install, prefix the command with
`uvx --from firebird-sql-mcp`:

```
fbmcp profile add mydb --host localhost --database D:\Data\MYDB.FDB --user SYSDBA
```

If you installed the package, register the server with your MCP client.
Claude Code:

```
claude mcp add firebird -- fbmcp
```

Claude Desktop, Cursor and friends (any stdio MCP client just runs `fbmcp`):

```json
{
  "mcpServers": {
    "firebird": { "command": "fbmcp" }
  }
}
```

Then ask away: "What tables are in mydb?", "Describe ORDERS", "Show the 10
most recent orders with customer names".

## CLI

| Command | What it does |
|---------|--------------|
| `fbmcp` | Start the stdio MCP server (what the MCP client runs) |
| `fbmcp profile add\|set\|rm\|list` | Manage connection profiles |
| `fbmcp cred set\|test\|rm --profile <name>` | Store, verify or remove a keyring password |
| `fbmcp init-config` | Create an example `profiles.toml` to edit by hand |

Profile options: `--port`, `--role`, `--charset` (default `AUTO`: detected from
the schema), `--none-charset` (what `charset NONE` data is assumed to be,
default `WIN1251`), `--timeout-ms` (statement timeout, 0 disables).

## Configuration

Profiles live in `profiles.toml` (`%APPDATA%\fbmcp` on Windows,
`~/.config/fbmcp` on Linux, `~/Library/Application Support/fbmcp` on macOS):

```toml
[defaults]
charset = "AUTO"                # AUTO = detect; or a Firebird charset (WIN1251, UTF8, ...)
statement_timeout_ms = 30000

[profiles.mydb]
host = "localhost"
database = 'D:\Data\MYDB.FDB'   # single quotes: no escaping of backslashes
user = "SYSDBA"
```

Environment variables: `FBMCP_PW__<PROFILE>` (password override for
containers/CI, beats the keyring), `FBMCP_FB_CLIENT_LIBRARY` (path to the
client library), `FBMCP_CONFIG_DIR` / `FBMCP_DATA_DIR` (relocate config and
audit log).

## License

[AGPL-3.0](LICENSE).

Firebird® is a registered trademark of the Firebird Foundation Incorporated.
This project is independent and not affiliated with or endorsed by the Firebird Project.
